gget-mcp

gget-mcp

MCP (Model Context Protocol) server for the gget bioinformatics library.

This server implements the Model Context Protocol (MCP) for gget, providing a standardized interface for accessing powerful bioinformatics tools and databases. MCP enables AI assistants and agents to perform complex genomics queries through structured interfaces.

The gget bioinformatics toolkit provides efficient querying of genomic databases and includes functions for:

• Gene and sequence information retrieval
• BLAST and sequence alignment
• Protein structure prediction
• Gene expression analysis
• Functional enrichment analysis
• And much more!

🚀 Quick Example: What Can You Do?

About MCP (Model Context Protocol)

Available Tools

Quick Start

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

# Verify installation
uv --version
uvx --version

Running with uvx

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

# Run the server in HTTP mode (default)
uvx gget-mcp server-http

# Run the server in stdio mode
uvx gget-mcp server-stdio

# Run the server in stdio-local mode with file saving
uvx gget-mcp server-local --output-dir ./gget_output

# Run the server in streamable HTTP mode on default (3002) port
uvx gget-mcp server-http

# Run on a specific port
uvx gget-mcp server-http --port 8000

# Run the server in SSE mode
uvx gget-mcp server-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:3002/mcp (with documentation at http://localhost:3002/docs). 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. Here are the actual configuration examples:

STDIO Mode Configuration (Recommended)

Use this configuration for most AI clients. Create or update your MCP configuration file:

{
  "mcpServers": {
    "gget-mcp": {
      "command": "uvx",
      "args": ["gget-mcp", "server-stdio"]
    }
  }
}

HTTP Mode Configuration

For HTTP mode:

{
  "mcpServers": {
    "gget-mcp": {
      "command": "uvx",
      "args": ["gget-mcp", "server-http"]
    }
  }
}

STDIO-Local Mode Configuration (File Saving)

Use this mode when you want to save large output files (sequences, structures, alignments) to disk instead of returning them as text:

{
  "mcpServers": {
    "gget-mcp": {
      "command": "uvx",
      "args": ["gget-mcp", "server-local", "--output-dir", "./gget_output"]
    }
  }
}

Local Development Configuration

For local development when you've cloned the repository:

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

Files Available:

• STDIO mode: mcp-config-stdio.json
• HTTP mode: mcp-config.json
• STDIO-Local mode: mcp-config-stdio-local.json
• Local development: mcp-config-stdio-debug.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 gget MCP server - just use the appropriate JSON configuration files provided above.

Inspecting gget MCP server

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

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

npx @modelcontextprotocol/inspector --config mcp-config-stdio-debug.json --server gget-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.

Repository setup

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

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

# Or start in STDIO mode  
uv run server-stdio

# Or start in STDIO-local mode (saves files locally)
uv run server-local

# Or start in SSE mode
uv run server-sse

Safety Features

• Input validation: Comprehensive parameter validation for all gget functions
• Error handling: Robust error handling with informative messages
• Rate limiting: Respectful usage of external APIs and databases
• Data validation: Type checking and data format validation

Testing & Verification

# Run all tests (excluding expensive judge tests)
uv run pytest -vvv -m "not judge"

# Run only fast tests (skip slow, integration, and judge tests)
uv run pytest -vvv -m "not slow and not integration and not judge"

# Run only integration tests
uv run pytest -vvv -m integration

# Run judge tests (expensive LLM tests - requires API keys and may cost money)
uv run pytest test/test_judge.py -vvv

# Run tests with coverage (excluding judge tests)
uv run pytest -vvv --cov=src/gget_mcp --cov-report=term-missing -m "not judge"

Note: 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.

Example Questions from Test Suite

Here are validated example questions that you can ask the AI assistant when using this MCP server:

• "Find information about the human TP53 gene and get its protein sequence."
• "What are the orthologs of BRCA1 gene across different species?"
• "Perform enrichment analysis for a set of cancer-related genes: TP53, BRCA1, BRCA2, ATM, CHEK2."
• "Get the 3D structure information for the protein encoded by the EGFR gene."
• "Find mutations in the COSMIC database for the PIK3CA gene."
• "Analyze gene expression patterns for insulin (INS) gene across different tissues."
• "Perform BLAST search with a DNA sequence to identify its origin: ATGGCGCCCGAACAGGGAC."
• "Find diseases associated with the APOE gene using OpenTargets."
• "Get reference genome information for mouse (Mus musculus)."
• "Align multiple protein sequences and identify conserved regions."

These questions are taken directly from our automated test suite and are validated to work correctly with the available gget tools.

Contributing

We welcome contributions from the community! 🎉 Whether you're a researcher, developer, or enthusiast interested in bioinformatics and genomics 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 query patterns
• 🔍 Data Quality: Help identify and report data inconsistencies or suggest improvements
• 🚀 Performance: Optimize queries, 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 bioinformatics community

Tutorials, videos, and user stories are especially valuable to us! We're working to push the bioinformatics 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 (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

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 bioinformatics research for everyone. 🧬✨

Known Issues

License

This project is licensed under the MIT License.

Acknowledgments

• gget - The amazing bioinformatics toolkit this server wraps
• FastMCP - The MCP server framework used
• Model Context Protocol - The protocol specification

Other MCP Servers by Longevity Genie

We also develop other specialized MCP servers for biomedical research:

• biothings-mcp - MCP server for BioThings.io APIs, providing access to gene annotation (mygene.info), variant annotation (myvariant.info), and chemical compound data (mychem.info)
• opengenes-mcp - MCP server for OpenGenes database, providing access to aging and longevity research data
• synergy-age-mcp - MCP server for SynergyAge database, providing access to synergistic and antagonistic longevity gene interactions

We are supported by:

HEALES - Healthy Life Extension Society

and

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