Addgene

Tests CI Python 3.11+ License: MIT uv

MCP (Model Context Protocol) server for Addgene - The Plasmid Repository

This server implements the Model Context Protocol (MCP) for Addgene, providing a standardized interface for accessing the world's largest repository of plasmid data. MCP enables AI assistants and agents to search, filter, and retrieve comprehensive plasmid information through structured interfaces.

The server provides direct access to Addgene's plasmid repository containing thousands of research-ready plasmids, complete with detailed metadata, sequence information, and availability data. Perfect for molecular biology research, synthetic biology, and genetic engineering applications.

The Addgene repository contains:

• Plasmid Search: Search through thousands of research plasmids with advanced filtering
• Sequence Information: Access to plasmid sequences in multiple formats (SnapGene, GenBank, FASTA)
• Metadata Access: Complete plasmid information including depositor, purpose, maps, and services
• Popular Plasmids: Access to trending and highly-cited plasmids in the research community

If you want to understand more about what the Model Context Protocol is and how to use it more efficiently, you can take the DeepLearning AI Course or search for MCP videos on YouTube.

Example Usage

About MCP (Model Context Protocol)

MCP is a protocol that bridges the gap between AI systems and specialized domain knowledge. It enables:

• Structured Access: Direct connection to authoritative plasmid repository data
• Natural Language Queries: Simplified interaction with specialized databases
• Type Safety: Strong typing and validation through FastMCP
• AI Integration: Seamless integration with AI assistants and agents

Available Tools

This server provides three main tools for interacting with the Addgene repository:

1. addgene_search_plasmids(...) - Search for plasmids with comprehensive filtering options
2. addgene_get_sequence_info(plasmid_id, format) - Get sequence download information for specific plasmids
3. addgene_get_popular_plasmids(page_size) - Retrieve trending and popular plasmids

Available Resources

1. resource://addgene_api-info - Complete API documentation and usage guidelines

Quick Start

Installing uv

# Download and install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version
uvx --version

uvx is a very nice tool that can run a python package installing it if needed.

Running with uvx

You can run the addgene-mcp server directly using uvx without cloning the repository:

# Run the server in streamable HTTP mode (default)
uvx addgene-mcp

# Or explicitly specify stdio mode
uvx addgene-mcp stdio

# Run the server in streamable HTTP mode on default (3001) port
uvx addgene-mcp server

# Run on a specific port
uvx addgene-mcp server --port 8000

# Run the server in SSE mode
uvx addgene-mcp sse

In cases when there are problems with uvx often they can be caused by cleaning uv cache:

uv cache clean

The HTTP mode will start a web server that you can access at http://localhost:3001/mcp. The STDIO mode is designed for MCP clients that communicate via standard input/output, while SSE mode uses Server-Sent Events for real-time communication.

Note: Currently, we do not have a Swagger/OpenAPI interface, so accessing the server directly in your browser will not show much useful information. To explore the available tools and capabilities, you should either use the MCP Inspector (see below) or connect through an MCP client to see the available tools.

Configuring your AI Client (Anthropic Claude Desktop, Cursor, Windsurf, etc.)

We provide preconfigured JSON files for different use cases:

• For STDIO mode (recommended): Use mcp-config-stdio.json
• For HTTP mode: Use mcp-config.json

Configuration Video Tutorial

For a visual guide on how to configure MCP servers with AI clients, check out our configuration tutorial video for our sister MCP server (biothings-mcp). The configuration principles are exactly the same for the Addgene MCP server - just use the appropriate JSON configuration files provided above.

Inspecting Addgene MCP server

npx @modelcontextprotocol/inspector --config mcp-config-stdio.json --server addgene-mcp

npx @modelcontextprotocol/inspector --config mcp-config.json --server addgene-mcp

npx @modelcontextprotocol/inspector

Integration with AI Systems

Simply point your AI client (like Cursor, Windsurf, ClaudeDesktop, VS Code with Copilot, or others) to use the appropriate configuration file from the repository.

Copy-Pasteable Configuration for addgene-mcp

Simply copy this JSON configuration to your MCP client (Cursor, Windsurf, Claude Desktop, etc.):

{
  "mcpServers": {
    "addgene-mcp": {
      "command": "uvx",
      "args": ["addgene-mcp"],
      "env": {
        "MCP_PORT": "3001",
        "MCP_HOST": "0.0.0.0",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

{
  "mcpServers": {
    "addgene-mcp": {
      "url": "http://localhost:3001/mcp",
      "type": "streamable-http",
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "addgene-mcp": {
      "command": "uv",
      "args": ["run", "addgene-mcp"],
      "env": {
        "MCP_PORT": "3001",
        "MCP_HOST": "0.0.0.0",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Repository setup

# Clone the repository
git clone https://github.com/longevity-genie/addgene-mcp.git
cd addgene-mcp
uv sync

Running the MCP Server

If you already cloned the repo you can run the server with uv:

# Start the MCP server locally (HTTP mode)
uv run server

# Or start in STDIO mode  
uv run stdio

# Or start in SSE mode
uv run sse

Available Tools Details

addgene_search_plasmids

Search for plasmids in the Addgene repository with comprehensive filtering options.

Parameters:

• query (optional): Free text search query
• page_size (optional): Number of results per page (default: 50, max: 50)
• page_number (optional): Page number for pagination (default: 1)
• expression (optional): Filter by expression system ("bacterial", "mammalian", "insect", "plant", "worm", "yeast")
• vector_types (optional): Filter by vector type
• species (optional): Filter by species
• plasmid_type (optional): Filter by plasmid type
• resistance_marker (optional): Filter by resistance marker
• bacterial_resistance (optional): Filter by bacterial resistance
• popularity (optional): Filter by popularity level ("high", "medium", "low")
• has_dna_service (optional): Filter by DNA service availability
• has_viral_service (optional): Filter by viral service availability
• is_industry (optional): Filter by industry availability

addgene_get_sequence_info

Get information about downloading a plasmid sequence.

Parameters:

• plasmid_id: Addgene plasmid ID (required)
• format (optional): Sequence format - "snapgene", "genbank", "fasta" (default: "snapgene")

addgene_get_popular_plasmids

Get popular plasmids from Addgene repository.

Parameters:

• page_size (optional): Number of results to return (default: 50, max: 50)

Data Models

PlasmidOverview

Contains comprehensive plasmid information:

• id: Addgene plasmid ID
• name: Plasmid name
• depositor: Name of the depositor
• purpose: Purpose/description
• article_url: Associated publication URL
• insert: Insert information
• tags: Tags associated with the plasmid
• mutation: Mutation information
• plasmid_type: Type of plasmid
• vector_type: Vector type/use
• popularity: Popularity level (high/medium/low)
• expression: Expression systems
• promoter: Promoter information
• map_url: Plasmid map image URL
• services: Available services
• is_industry: Whether available to industry

SearchResult

Contains search results and metadata:

• plasmids: List of PlasmidOverview objects
• count: Number of results returned
• query: Search query used
• page: Page number
• page_size: Results per page
• filters_applied: Dictionary of applied filters

SequenceDownloadInfo

Contains sequence download information:

• plasmid_id: Plasmid ID
• download_url: Direct download URL
• format: Sequence format
• available: Whether sequence is available for download

Example Queries

# Search for CRISPR-related plasmids
result = await search_plasmids(query="CRISPR Cas9", page_size=50)

# Search for mammalian expression vectors
result = await search_plasmids(
    expression="mammalian",
    vector_types="expression",
    page_size=15
)

# Find popular bacterial expression plasmids
result = await search_plasmids(
    expression="bacterial",
    popularity="high",
    page_size=50
)

# Search for plasmids containing a specific gene
result = await search_plasmids(
    query="GFP fluorescent protein",
    plasmid_type="reporter"
)

# Get GenBank format sequence for a plasmid
seq_info = await get_sequence_info(
    plasmid_id=12345,
    format="genbank"
)

Research Applications

Safety Features

• Rate limiting: Respectful scraping with appropriate delays
• Error handling: Comprehensive error handling with informative messages
• Input validation: Robust validation of all input parameters
• Retry logic: Automatic retry for network-related failures

Testing & Verification

The MCP server includes comprehensive tests for all functionality:

Running Tests

Run tests for the MCP server:

# Set testing environment and run all tests
uv run pytest -vvv -s

Test Coverage

Our test suite includes:

• Unit tests: Testing individual components and functions
• Integration tests: Testing end-to-end functionality
• Mock tests: Testing with simulated responses for consistent CI
• Filter tests: Testing all search filter combinations
• Error handling tests: Testing error conditions and edge cases

Using the MCP Inspector is optional. Most MCP clients (like Cursor, Windsurf, etc.) will automatically display the available tools from this server once configured. However, the Inspector can be useful for detailed testing and exploration.

If you choose to use the Inspector via npx, ensure you have Node.js and npm installed. Using nvm (Node Version Manager) is recommended for managing Node.js versions.

Contributing

We welcome contributions from the community! 🎉 Whether you're a researcher, developer, or enthusiast interested in molecular biology and plasmid research, there are many ways to get involved:

We especially encourage you to try our MCP server and share your feedback with us! Your experience using the server, any issues you encounter, and suggestions for improvement are incredibly valuable for making this tool better for the entire research community.

Ways to Contribute

• 🐛 Bug Reports: Found an issue? Please open a GitHub issue with detailed information
• 💡 Feature Requests: Have ideas for new functionality? We'd love to hear them!
• 📝 Documentation: Help improve our documentation, examples, or tutorials
• 🧪 Testing: Add test cases, especially for edge cases or new search patterns
• 🔍 Data Quality: Help identify and report data inconsistencies or suggest improvements
• 🚀 Performance: Optimize scraping, improve caching, or enhance server performance
• 🌐 Integration: Create examples for new MCP clients or AI systems
• 🎥 Tutorials & Videos: Create tutorials, video guides, or educational content showing how to use MCP servers
• 📖 User Stories: Share your research workflows and success stories using our MCP servers
• 🤝 Community Outreach: Help us evangelize MCP adoption in the molecular biology community

Tutorials, videos, and user stories are especially valuable to us! We're working to push the molecular biology community toward AI adoption, and real-world examples of how researchers use our MCP servers help demonstrate the practical benefits and encourage wider adoption.

Getting Started

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Run the test suite (TESTING=true uv run pytest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow the existing code style (we use ruff for formatting and linting)
• Add tests for new functionality
• Update documentation as needed
• Keep commits focused and write clear commit messages
• Ensure all tests pass before submitting PR

Questions or Ideas?

Don't hesitate to open an issue for discussion! We're friendly and always happy to help newcomers get started. Your contributions help advance open science and molecular biology research for everyone. 🧬✨

Known Issues

Windows Compatibility

The MCP server has not been fully tested on Windows systems. Some users have reported that searches either crash or return no results on Windows. If you encounter issues on Windows, please report them as GitHub issues with details about your Windows version and error messages.

Scraping Limitations

This MCP server relies on web scraping the Addgene website. While we implement respectful scraping practices with appropriate delays and error handling, the server's functionality depends on the current structure of the Addgene website. Changes to the website may require updates to the scraping logic.

Rate Limiting

To be respectful to Addgene's servers, we implement rate limiting. For high-volume usage, consider implementing caching or contacting Addgene about API access.

Test Coverage

While we provide comprehensive tests including mock data for CI stability, not all test cases have been validated against real-time Addgene data. Some edge cases may need additional validation.

License

This project is licensed under the MIT License.

Acknowledgments

• Addgene for maintaining the world's largest repository of plasmid data
• Model Context Protocol for the protocol specification
• FastMCP for the MCP server framework

This project is part of the Longevity Genie organization, which develops open-source AI assistants and libraries for health, genetics, and longevity research.

MCP Servers

We also develop other specialized MCP servers for biomedical research:

• gget-mcp: A powerful bioinformatics toolkit for genomics queries and analysis, wrapping the popular gget library.
• opengenes-mcp: A queryable database for aging and longevity research from the OpenGenes project.
• synergy-age-mcp: A database of synergistic and antagonistic genetic interactions in longevity from SynergyAge.
• biothings-mcp: Access to BioThings.io APIs for comprehensive gene, variant, chemical, and taxonomic data.
• pharmacology-mcp: Access to the Guide to PHARMACOLOGY database for drug, target, and ligand information.

We are supported by:

HEALES

HEALES - Healthy Life Extension Society

and

IBIMA

IBIMA - Institute for Biostatistics and Informatics in Medicine and Ageing Research