SmartAPI MCP Server

Create MCP (Model Context Protocol) servers for one or multiple APIs registered in the SmartAPI registry.

Overview

The SmartAPI MCP Server enables integration between MCP-compatible clients and APIs registered in the SmartAPI registry. This allows for seamless discovery and interaction with bioinformatics and life sciences APIs through standardized MCP protocols.

Built on top of the AWS Labs OpenAPI MCP Server, this project extends MCP support to the extensive collection of APIs available in the SmartAPI registry, with special focus on bioinformatics and life sciences APIs.

Requirements

Python 3.10 or higher
Network access to SmartAPI registry (https://smart-api.info)
Dependencies: awslabs_openapi_mcp_server>=0.2.4

Features

🔍 SmartAPI Integration: Direct integration with the SmartAPI registry for API discovery
🏗️ MCP Protocol Support: Full MCP (Model Context Protocol) server implementation
🔄 Async Architecture: Built with modern Python async/await patterns for high performance
📖 OpenAPI Validation: Automatic OpenAPI specification parsing and validation
🛠️ CLI Interface: Easy-to-use command-line interface with multiple configuration options
🧬 Bioinformatics Focus: Pre-configured API sets for bioinformatics and life sciences
🎯 Flexible Configuration: Support for environment variables, arguments, and configuration files
🚀 Multiple Transport Modes: Support for both stdio and HTTP transport protocols
🧪 Comprehensive Testing: Full test suite with 99% code coverage

Installation

From PyPI (recommended)

pip install smartapi-mcp

From Source

git clone https://github.com/biothings/smartapi-mcp.git
cd smartapi-mcp
pip install -e .

Development Installation

git clone https://github.com/biothings/smartapi-mcp.git
cd smartapi-mcp
pip install -e ".[dev]"

Using with MCP Clients

Using with uvx (Recommended)

uvx is a tool for running Python applications in isolated environments. This is the recommended way to run smartapi-mcp for MCP client integration:

Installation and Basic Usage

# Install uvx if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# or with homebrew on macOS
brew install uv

# Run smartapi-mcp with uvx (automatically installs if needed)
uvx smartapi-mcp --api_set biothings_core

# Run with specific version
uvx smartapi-mcp@0.1.0 --api_set biothings_core

# Run with additional arguments
uvx smartapi-mcp --smartapi_id 59dce17363dce279d389100834e43648 --server_name "MyGene MCP Server"

Using with Claude Desktop

To use smartapi-mcp with Claude Desktop, add the following configuration to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "smartapi-biothings-core": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--api_set", "biothings_core", "--server_name", "BioThings Core APIs"]
    },
    "smartapi-mygene": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--smartapi_id", "59dce17363dce279d389100834e43648", "--server_name", "MyGene.info API"]
    },
    "smartapi-myvariant": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--smartapi_id", "09c8782d9f4027712e65b95424adba79", "--server_name", "MyVariant.info API"]
    }
  }
}

Using with Other MCP Clients

For other MCP clients that support external MCP servers, you can typically configure them by providing:

Command: uvx
Arguments: ["smartapi-mcp", "--api_set", "biothings_core"] (or other desired arguments)
Working Directory: Optional, can be any directory
Environment Variables: Optional, see Environment Variables section

MCP Server Configuration Examples

Basic Bioinformatics Setup

{
  "mcpServers": {
    "biothings-core": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--api_set", "biothings_core"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Advanced Multi-API Setup

{
  "mcpServers": {
    "biothings-comprehensive": {
      "command": "uvx",
      "args": [
        "smartapi-mcp",
        "--smartapi_ids",
        "59dce17363dce279d389100834e43648,09c8782d9f4027712e65b95424adba79,8f08d1446e0bb9c2b323713ce83e2bd3",
        "--server_name",
        "Comprehensive Bioinformatics APIs",
        "--log-level",
        "DEBUG"
      ]
    }
  }
}

Development/Testing Setup

{
  "mcpServers": {
    "smartapi-dev": {
      "command": "uvx",
      "args": [
        "smartapi-mcp",
        "--api_set",
        "biothings_test",
        "--log-level",
        "DEBUG"
      ],
      "env": {
        "SMARTAPI_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Environment Variables for MCP Configuration

You can also use environment variables in your MCP client configuration:

{
  "mcpServers": {
    "smartapi-configured": {
      "command": "uvx",
      "args": ["smartapi-mcp"],
      "env": {
        "SMARTAPI_API_SET": "biothings_core",
        "SERVER_NAME": "BioThings Core MCP Server",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Alternative Installation Methods for MCP Clients

Using pip in a Virtual Environment

If you prefer not to use uvx, you can create a dedicated virtual environment:

# Create and activate virtual environment
python -m venv smartapi-mcp-env
source smartapi-mcp-env/bin/activate  # On Windows: smartapi-mcp-env\Scripts\activate

# Install smartapi-mcp
pip install smartapi-mcp

# Test the installation
smartapi-mcp --api_set biothings_core

Then configure your MCP client to use the full path to the executable:

{
  "mcpServers": {
    "smartapi-biothings": {
      "command": "/path/to/smartapi-mcp-env/bin/smartapi-mcp",
      "args": ["--api_set", "biothings_core"]
    }
  }
}

Using System-wide Installation

# Install globally (not recommended for most users)
pip install smartapi-mcp

# Find the installation path
which smartapi-mcp

MCP client configuration:

{
  "mcpServers": {
    "smartapi-biothings": {
      "command": "smartapi-mcp",
      "args": ["--api_set", "biothings_core"]
    }
  }
}

Troubleshooting MCP Client Integration

Server Not Starting

Check uvx installation:
```
uvx --version
```

Test server manually:

uvx smartapi-mcp --api_set biothings_core --log-level DEBUG

Check MCP client logs for specific error messages

Tools Not Appearing in Client

Verify server is running with tools registered:

uvx smartapi-mcp --api_set biothings_core --log-level DEBUG 2>&1 | grep -i "tool"

Check API connectivity:

curl -s https://mygene.info/v3/metadata | head -20

Try a smaller API set first:

uvx smartapi-mcp --smartapi_id 59dce17363dce279d389100834e43648

Performance Issues

Use specific SmartAPI IDs instead of large API sets
Enable only the APIs you actually need

Consider using HTTP transport for better performance with multiple concurrent requests:

{
  "mcpServers": {
    "smartapi-http": {
      "command": "uvx",
      "args": ["smartapi-mcp", "--api_set", "biothings_core", "--transport", "http", "--port", "8001"]
    }
  }
}

Quick Start

Command Line Usage

Start with a predefined API set (recommended)

# Use BioThings core APIs (MyGene, MyVariant, MyChem, MyDisease)
smartapi-mcp --api_set biothings_core

# Use all BioThings APIs (with some exclusions)
smartapi-mcp --api_set biothings_all

Start with specific SmartAPI IDs

# Single API
smartapi-mcp --smartapi_id 59dce17363dce279d389100834e43648

# Multiple APIs
smartapi-mcp --smartapi_ids "59dce17363dce279d389100834e43648,09c8782d9f4027712e65b95424adba79"

Start with HTTP transport (instead of stdio)

# HTTP mode on localhost:8000 (default)
smartapi-mcp --api_set biothings_core --transport http

# Custom host and port
smartapi-mcp --api_set biothings_core --transport http --host 0.0.0.0 --port 9000

Advanced options

# Custom logging level
smartapi-mcp --api_set biothings_core --log-level DEBUG

# Custom server name
smartapi-mcp --api_set biothings_core --server_name "My Custom MCP Server"

# Query-based API discovery
smartapi-mcp --smartapi_q "tags.name=biothings"

# Exclude specific APIs
smartapi-mcp --api_set biothings_all --smartapi_exclude_ids "api_id_1,api_id_2"

Python API Usage

import asyncio
from smartapi_mcp import (
    get_smartapi_ids,
    load_api_spec,
    get_mcp_server,
    get_merged_mcp_server,
    PREDEFINED_API_SETS
)

async def main():
    # Get SmartAPI IDs using a query
    smartapi_ids = await get_smartapi_ids("tags.name=biothings")
    print(f"Found {len(smartapi_ids)} APIs matching the query")
    
    # Load API specification for a specific SmartAPI
    api_spec = load_api_spec("59dce17363dce279d389100834e43648")  # MyGene.info
    print(f"Loaded API: {api_spec.get('info', {}).get('title', 'Unknown')}")
    
    # Create MCP server for a single API
    server = await get_mcp_server(
        smartapi_id="59dce17363dce279d389100834e43648",
        server_name="MyGene MCP Server"
    )
    
    # Create merged MCP server for multiple APIs (recommended approach)
    merged_server = await get_merged_mcp_server(
        api_set="biothings_core",  # Use predefined set
        server_name="BioThings Core MCP Server"
    )
    
    # Or with specific SmartAPI IDs
    merged_server = await get_merged_mcp_server(
        smartapi_ids=[
            "59dce17363dce279d389100834e43648",  # MyGene.info
            "09c8782d9f4027712e65b95424adba79",  # MyVariant.info
        ],
        server_name="Custom MCP Server"
    )
    
    # Show available predefined API sets
    print(f"Available API sets: {PREDEFINED_API_SETS}")
    
    # Run server with stdio transport (default for MCP)
    merged_server.run()
    
    # Or run with HTTP transport
    # merged_server.run(transport="http", host="localhost", port=8000)

if __name__ == "__main__":
    asyncio.run(main())

API Examples

BioThings Core APIs

When you use --api_set biothings_core, you get access to these powerful bioinformatics APIs:

MyGene.info (59dce17363dce279d389100834e43648): Gene annotation and information
MyVariant.info (09c8782d9f4027712e65b95424adba79): Variant annotation and information
MyChem.info (8f08d1446e0bb9c2b323713ce83e2bd3): Chemical and drug information
MyDisease.info (671b45c0301c8624abbd26ae78449ca2): Disease information and associations

Usage with MCP Clients

Once the server is running, MCP-compatible clients can discover and use the available tools. Each API endpoint becomes an available MCP tool with:

Tool discovery: Clients can list all available API endpoints
Parameter validation: Automatic parameter validation based on OpenAPI specs
Rich descriptions: Each tool includes detailed descriptions from the API documentation
Error handling: Proper error responses for invalid requests

Configuration

The server supports multiple configuration methods:

Environment Variables

# SmartAPI configuration
export SMARTAPI_ID="59dce17363dce279d389100834e43648"
export SMARTAPI_IDS="id1,id2,id3"
export SMARTAPI_Q="tags.name=biothings"
export SMARTAPI_API_SET="biothings_core"
export SMARTAPI_EXCLUDE_IDS="exclude_id1,exclude_id2"

# Server configuration
export SERVER_NAME="My SmartAPI MCP Server"
export TRANSPORT="http"
export HOST="localhost"
export PORT="8000"

# Then run without arguments
smartapi-mcp

Command Line Arguments

All configuration can be provided via command line arguments (see Quick Start section above).

Predefined API Sets

The following predefined API sets are available:

biothings_core: Core BioThings APIs (MyGene, MyVariant, MyChem, MyDisease)
biothings_test: Core APIs plus SemmedDB (useful for testing)
biothings_all: All BioThings APIs (with some exclusions for stability)

Configuration Priority

Command line arguments (highest priority)
Environment variables
Default values (lowest priority)

Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/biothings/smartapi-mcp.git
cd smartapi-mcp

# Install development dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=smartapi_mcp --cov-report=html

# Run specific test file
pytest tests/test_basic.py

Code Quality

# Check and fix linting issues
ruff check .
ruff check . --fix

# Format code
ruff format .

Building the Package

# Build source and wheel distributions
python -m build

# Check the built package
twine check dist/*

Publishing to PyPI

Manual Publishing

# Build the package
python -m build

# Upload to Test PyPI (optional)
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*

Automated Publishing

This repository includes GitHub Actions workflows for automated testing and publishing:

Test Workflow (.github/workflows/test.yml): Runs on every push and pull request
Publish Workflow (.github/workflows/publish.yml): Publishes to PyPI on release

To publish a new version:

Update the version in pyproject.toml and smartapi_mcp/__init__.py
Commit the version changes
Create and push a git tag: git tag v0.1.0 && git push origin v0.1.0
Create a new release on GitHub
The publish workflow will automatically build and upload to PyPI

Manual Workflow Trigger

You can also manually trigger the publish workflow to upload to Test PyPI:

Go to the Actions tab in your GitHub repository
Select "Publish Python Package"
Click "Run workflow"
Choose "Publish to Test PyPI" option

Contributing

We welcome contributions! Please see our contributing guidelines for details.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for your changes
Ensure tests pass (pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Troubleshooting

Common Issues

No tools or resources registered

WARNING: No tools or resources were registered. This might indicate an issue with the API specification or authentication.

Solution: This usually happens when:

The SmartAPI ID is invalid or the API is down
The OpenAPI specification has validation errors
Network connectivity issues

Try with a known working API set: smartapi-mcp --api_set biothings_core

Server fails to start

Check your Python version: Requires Python 3.10+

python --version

Verify installation:

pip show smartapi-mcp

HTTP mode connection issues

If using HTTP transport mode and clients can't connect:

Check if the port is available: netstat -an | grep :8000
Try binding to all interfaces: --host 0.0.0.0
Check firewall settings

Getting Help

Enable debug logging: --log-level DEBUG
Check the GitHub Issues
Contact us at help@biothings.io

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Related Projects

SmartAPI Registry - Registry of biomedical and life sciences APIs
Model Context Protocol (MCP) - Standard protocol for AI model-tool integration
BioThings APIs - High-performance bioinformatics APIs
AWS Labs OpenAPI MCP Server - Base MCP server framework

Citation

If you use SmartAPI MCP Server in your research or applications, please cite:

SmartAPI MCP Server: Bridging Bioinformatics APIs with Model Context Protocol
BioThings Team. (2024). https://github.com/biothings/smartapi-mcp

Support

For questions and support:

📖 Documentation: README
🐛 Bug Reports: GitHub Issues
💬 Questions: GitHub Discussions
📧 Email: help@biothings.io

SmartAPI MCP Server is developed and maintained by the BioThings Team at The Scripps Research Institute.

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github/workflows		.github/workflows
.zed		.zed
scripts		scripts
smartapi_mcp		smartapi_mcp
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.md		README.md
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
requirements.txt		requirements.txt
setup.py		setup.py

License

biothings/smartapi-mcp

Folders and files

Latest commit

History

Repository files navigation

SmartAPI MCP Server

Overview

Requirements

Features

Installation

From PyPI (recommended)

From Source

Development Installation

Using with MCP Clients

Using with uvx (Recommended)

Installation and Basic Usage

Using with Claude Desktop

Using with Other MCP Clients

MCP Server Configuration Examples

Basic Bioinformatics Setup

Advanced Multi-API Setup

Development/Testing Setup

Environment Variables for MCP Configuration

Alternative Installation Methods for MCP Clients

Using pip in a Virtual Environment

Using System-wide Installation

Troubleshooting MCP Client Integration

Server Not Starting

Tools Not Appearing in Client

Performance Issues

Quick Start

Command Line Usage

Start with a predefined API set (recommended)

Start with specific SmartAPI IDs

Start with HTTP transport (instead of stdio)

Advanced options

Python API Usage

API Examples

BioThings Core APIs

Usage with MCP Clients

Configuration

Environment Variables

Command Line Arguments

Predefined API Sets

Configuration Priority

Development

Setting up Development Environment

Running Tests

Code Quality

Building the Package

Publishing to PyPI

Manual Publishing

Automated Publishing

Manual Workflow Trigger

Contributing

Troubleshooting

Common Issues

No tools or resources registered

Server fails to start

HTTP mode connection issues

Getting Help

License

Related Projects

Citation

Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Contributors 2

Uh oh!

Languages

Packages