pankajrajdeo/toppgene-mcp-server

🧬 ToppGene MCP Server

Model Context Protocol (MCP) server that gives AI assistants direct access to the ToppGene Suite for functional enrichment analysis. Supply a gene list and receive statistically ranked pathways, diseases, phenotypes, and other annotations—plus a TSV file with the complete results for downstream analysis.

🚀 Quick Start

🎥 Demo

1. Clone and enter the project

   git clone https://github.com/<your-account>/toppgene-mcp-server.git
   cd toppgene-mcp-server
   

2. (Optional) Create a virtual environment

   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   

3. Install dependencies

   pip install -e .
   # or: pip install -r requirements.txt
   

4. Run the server

   python toppgene_mcp.py
   # or, after installing in editable mode:
   toppgene-mcp
   

The server runs over stdio (default MCP transport). Leave it running while your MCP client connects.

🧩 Connect From Popular MCP Clients

Claude Desktop

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "toppgene": {
      "command": "python3",
      "args": ["/absolute/path/to/toppgene_mcp.py"]
    }
  }
}

Restart Claude Desktop; the 🔌 MCP indicator should show toppgene as available.

Cursor / Continue / Custom Clients

Any MCP-compatible client can launch the server with the same command/args pair shown above.

🔍 Tools & Capabilities

• toppgene_enrichment_analysis: Core tool. Accepts 1–1000 genes (HGNC, Ensembl, Entrez, UniProt, RefSeq) and returns enriched terms across 19 annotation categories.
• Automatic gene symbol → Entrez ID conversion via the ToppGene lookup API.
• Configurable p-value threshold, multiple-testing correction, result limits, and response verbosity (concise or detailed).
• Supports Markdown or JSON responses so agents can narrate findings or post-process raw data.

Each request also writes a timestamped TSV file under outputs/ containing the full enrichment result table (Category, Term ID, Term Name, p-values, overlaps, etc.). This lets agents run follow-up code execution such as plotting or filtering.

🧪 Optional LangChain Agent

An example LangChain agent (toppgene_agent.py) demonstrates how to orchestrate the MCP tools with OpenAI’s GPT models. To try it:

pip install -e .[agent]
cp .env.example .env  # then add your OPENAI_API_KEY
python test_agent.py

The agent script connects to the local MCP server, loads available tools, and answers natural-language questions about the supplied genes.

📁 Project Layout

toppgene-mcp-server/
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── toppgene_mcp.py          # MCP server entry point
├── toppgene_agent.py        # Optional LangChain agent
├── test_agent.py            # Smoke test for the agent
├── setup_claude.sh          # Helper script for Claude Desktop config
├── outputs/                 # Timestamped TSV results (gitignored)
├── docs/
│   ├── INSTALL.md           # Legacy installation notes
│   ├── CLAUDE_SETUP.md      # Detailed Claude Desktop walkthrough
│   └── TSV_FEATURE.md       # TSV output behaviour
└── toppgene_mcp.mov         # Demo walkthrough

📚 Additional Documentation

• docs/INSTALL.md – quick install steps.
• docs/CLAUDE_SETUP.md – full Claude Desktop guide and troubleshooting tips.
• docs/TSV_FEATURE.md – deep dive on TSV output workflows.

🛡️ License

Released under the . Pull requests and issue reports are welcome!