<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>

![Python](https://www.python.org/) ![License: BSD-3](LICENSE) ![Powered by GenePattern](https://genepattern.ucsd.edu/)

</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: ``bash pip install -r requirements.txt ``

With uv: ``bash 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: ``bash export GENEPATTERN_KEY="YOUR_TOKEN" ``

Option B — Generate one with the included helper: ```bash 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:

Look up the PreprocessDataset module LSID automatically
Submit the job to GenePattern cloud
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: ``bash 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: ``bash 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): ```bash 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: ``json { "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: ``json { "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.

GenePattern MCP Server