GenePattern MCP Server

<h1 align="center">GenePattern MCP Server</h1>

<div align="center"> <em>Bridge any AI coding assistant directly to GenePattern — run bioinformatics modules, manage cloud jobs, and stream results, all through natural language.</em>

</div>

---

Why GenePattern MCP?

Modern AI assistants are extraordinarily good at reasoning — but they can't run a gene expression pipeline or execute bioinformatics on their own. We built GenePattern MCP to close that gap.

By implementing the Model Context Protocol (MCP), this server exposes the full GenePattern REST API as a set of structured, type-safe tools that any MCP-compatible AI client (Claude, Cursor, GitHub Copilot, and more) can call directly. The result: your AI assistant can now:

• 🧬 Search, inspect, and execute hundreds of peer-reviewed genomic analysis modules
• 🤖 Chain bioinformatic tasks into multi-step AI-driven workflows — no manual API calls required
• ☁️ Scale effortlessly on GenePattern's cloud infrastructure at cloud.genepattern.org
• 📊 Guarantee reproducibility — every job is tracked by LSID and stored with full provenance

From raw expression data to publication-ready insights — powered by a conversation.

---

Feature Highlights

Feature	Description
🧬 Genomic Integration	Access 200+ curated modules: differential expression, pathway analysis, single-cell, proteomics, and more
🤖 AI/ML Workflows	Let your LLM orchestrate multi-step pipelines end-to-end via natural language prompts
☁️ Cloud Scalability	Jobs run on GenePattern's managed cloud — no local compute needed
📊 Reproducible Science	Every module is versioned by LSID; every job is logged and retrievable
🔌 Multi-Transport	stdio for local clients, streamable-http / SSE for remote or containerized deployments
🔐 Flexible Auth	Pluggable AuthHandler system — env-var token, HTTP Bearer header, or bring your own
🐳 Docker-Ready	Official image at genepattern/mcp; zero-config cloud deployment

---

Prerequisites

• Python 3.11+
• A GenePattern API token (see Get a Token below)
• pip or uv

---

Installation

With pip:

pip install -r requirements.txt

With uv:

uv venv && source .venv/bin/activate
uv pip install -r requirements.txt

---

Get a GenePattern Token

You need a Bearer token to authenticate with GenePattern.

Option A — You already have a token:

export GENEPATTERN_KEY="YOUR_TOKEN"

Option B — Generate one with the included helper:

python get-token.py -s https://cloud.genepattern.org/gp \
                    -u YOUR_USERNAME \
                    -p YOUR_PASSWORD
# Follow the printed instructions to export GENEPATTERN_KEY

---

Quick Start

1. Start the server (local stdio — recommended for AI clients)

export GENEPATTERN_KEY="YOUR_TOKEN"
python server.py --transport stdio

2. Run a bioinformatic analysis via your AI assistant

Once connected, ask your AI assistant something like:

"Run PreprocessDataset on all_aml_test.gct, threshold at 20/1500, and download the result."

The MCP server will:

1. Look up the PreprocessDataset module LSID automatically
2. Submit the job to GenePattern cloud
3. Poll for completion and return the output file paths

3. Explore available tools interactively

mcp dev server.py

---

Running the Server

The server supports three transport modes via FastMCP.

Mode	Command
stdio (local AI clients)	python server.py --transport stdio
HTTP (remote / Docker)	python server.py --transport streamable-http --host 0.0.0.0 --port 3000
SSE	python server.py --transport sse --host 0.0.0.0 --port 3000

Testing with GenePattern Copilot:

python server.py --transport streamable-http --host 0.0.0.0 --port 3000 \
    --auth-handler genepattern_mcp._shared.HeaderAuthHandler

---

Docker

Pull and run the official image in seconds:

docker pull genepattern/mcp

Run in HTTP mode:

docker run --rm \
  -e GENEPATTERN_URL=https://cloud.genepattern.org/gp \
  -e GENEPATTERN_KEY=YOUR_TOKEN \
  -e FASTMCP_TRANSPORT=streamable-http \
  -e FASTMCP_HOST=0.0.0.0 \
  -e FASTMCP_PORT=3000 \
  -p 3000:3000 \
  genepattern/mcp

Using Authorization header instead of an env token (stateless, multi-user HTTP):

docker run --rm -p 3000:3000 \
  -e AUTH_HANDLER=genepattern_mcp._shared.HeaderAuthHandler \
  -e FASTMCP_TRANSPORT=streamable-http \
  genepattern/mcp
# Clients send: Authorization: Bearer YOUR_TOKEN

Note: stdio transport is impractical inside Docker containers. Use streamable-http when containerized.

---

Connect from MCP-Enabled Clients

Claude Code (VS Code)

Local stdio (recommended):

{
  "mcpServers": {
    "genepattern": {
      "command": "python",
      "args": ["server.py", "--transport", "stdio"],
      "env": {
        "GENEPATTERN_URL": "https://cloud.genepattern.org/gp",
        "GENEPATTERN_KEY": "${env:GENEPATTERN_KEY}"
      }
    }
  }
}

Remote HTTP server:

{
  "mcpServers": {
    "genepattern": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp",
      "env": {
        "GENEPATTERN_URL": "https://cloud.genepattern.org/gp",
        "GENEPATTERN_KEY": "<GP API TOKEN>"
      }
    }
  }
}

Cursor

Add via Cursor Settings → MCP Servers:

{
  "mcpServers": {
    "genepattern": {
      "command": "python",
      "args": ["server.py", "--transport", "stdio"],
      "environment": {
        "GENEPATTERN_URL": "https://cloud.genepattern.org/gp",
        "GENEPATTERN_KEY": "YOUR_TOKEN"
      }
    }
  }
}

Other MCP Clients

• stdio: invoke server.py --transport stdio
• HTTP/SSE: connect to http://HOST:PORT using the appropriate transport
• Multi-user HTTP: set AUTH_HANDLER=genepattern_mcp._shared.HeaderAuthHandler and pass Authorization: Bearer <token> per request

---

Configuration Reference

All CLI flags have a corresponding environment variable. Environment variables are applied before CLI arguments.

Flag	Env Variable	Default	Description
--genepattern, -g	GENEPATTERN_URL	https://cloud.genepattern.org/gp	GenePattern server URL (include /gp)
--key, -k	GENEPATTERN_KEY	None	Your GenePattern API Bearer token
--auth-handler, -a	AUTH_HANDLER	EnvAuthHandler	Full Python path to an AuthHandler class (see below)
--transport, -t	FASTMCP_TRANSPORT	streamable-http	Transport protocol: streamable-http, stdio, or sse
--port, -p	FASTMCP_PORT	3000	Port to listen on (HTTP/SSE only)
--host, -H	FASTMCP_HOST	0.0.0.0	Host interface to bind (HTTP/SSE only)
--local-files, -l	LOCAL_FILES_ENABLED	True	Enable local file upload/download tools

Auth Handlers

Class	Behavior
genepattern_mcp._shared.EnvAuthHandler	(default) Reads GENEPATTERN_KEY from environment
genepattern_mcp._shared.HeaderAuthHandler	Reads Authorization: Bearer <token> from each HTTP request
custom	Subclass AuthHandler and implement get_api_key(context)

Local File Tools

When --local-files is False, the following tools are disabled:

• upload_whole_file
• download_job_results
• upload_file
• upload_job_input_from_body
• upload_job_input_from_form
• upload_job_output

---

Security Notes

• Treat GENEPATTERN_KEY like a password — prefer environment variables over hardcoding tokens.
• When exposing the HTTP server to a network, put it behind a reverse proxy with TLS (e.g., nginx + Let's Encrypt).
• For multi-user deployments, use HeaderAuthHandler so each user supplies their own token per request.

---

Contributing & Community

We believe the best bioinformatics tools are built by the community, for the community. All skill levels welcome — whether you're a genomics researcher, an ML engineer, or just someone who wants to ask an AI to run a pathway analysis.

Ways to get involved:

• 🐛 Found a bug? Open an issue — we triage actively.
• 💡 Have a feature idea? Start a Discussion — we love hearing about new use cases.
• 🔧 Want to contribute code? Fork the repo, make your changes, and open a PR. Please include tests.
• 💬 Need help? Reach out on the GenePattern Community Forum or tag us in an issue.

# Get started with development
git clone https://github.com/genepattern/genepattern-mcp.git
cd genepattern-mcp
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
mcp dev server.py   # Explore all tools interactively

---

Citing This Work

If GenePattern MCP accelerates your research, please cite the underlying GenePattern platform:

Reich M, Liefeld T, Gould J, Lerner J, Tamayo P, Mesirov JP. GenePattern 2.0 Nature Genetics 38 no. 5 (2006): pp500-501 Google Scholar

---

License

Distributed under the BSD 3-Clause License. See LICENSE for details.