🧬🤖 Isabl MCP Server

_Talk to your genomics data. MCP server + knowledge base for the Isabl platform._

[!TIP] 👋 New to Isabl? Isabl is free to use for Research and Academy. 🔐 Request Access Here) 📖 View Documentation

Install

Claude Code

/plugin marketplace add juanesarango/isabl-mcp
/plugin install isabl

Installs the MCP server (11 tools) + 8 guided skills as /isabl-* slash commands (type /isabl to see all). Credentials are auto-discovered from ~/.isabl/settings.json. For MCP only (no skills): claude mcp add isabl -- uvx isabl-mcp.

Cursor

Click the badge above, or add to .cursor/mcp.json:

{
  "mcpServers": {
    "isabl": {
      "command": "uvx",
      "args": ["isabl-mcp"],
      "env": {
        "ISABL_API_URL": "https://your-isabl-instance.com/api/v1/",
        "ISABL_API_TOKEN": "your-token"
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.isabl]
command = "uvx"
args = ["isabl-mcp"]
env = { "ISABL_API_URL" = "https://your-isabl-instance.com/api/v1/", "ISABL_API_TOKEN" = "your-token" }

Other MCP clients

uvx isabl-mcp        # run directly, no install needed
pip install isabl-mcp # or install globally

Works with any MCP-compatible client (Windsurf, Zed, Claude Desktop, etc.).

[!TIP] You can use the Isabl MCP directly through <img src="https://upstash.gallerycdn.vsassets.io/extensions/upstash/context7-mcp/1.0.1/1754329920224/Microsoft.VisualStudio.Services.Icons.Default" height="16"> [Context7](https://context7.com/juanesarango/isabl-mcp)

What's included

Credentials

The server auto-discovers your API URL and token from ~/.isabl/settings.json (created by isabl_cli login). No env vars needed if you've already logged in.

You can also set them explicitly:

export ISABL_API_URL="https://your-isabl-instance.com/api/v1/"
export ISABL_API_TOKEN="your-token"

Env vars always take precedence over the settings file.

What can I ask?

"Show me all failed analyses in project 102"

"How many WGS experiments do we have for patient ISB_H000001?"

"Analysis 12345 failed. Show me the error logs and help me figure out what went wrong"

"Get the VCF file paths from all succeeded MUTECT analyses in project 102"

"How do I write a new paired tumor-normal application?"

"Give me a summary of project 102"

Tools (11)

Skills (8) — Claude Code only

Skills are guided multi-step workflows available as /isabl-* slash commands. Included automatically with the plugin install.

How it works

You (plain English) → AI Assistant → MCP Server → Isabl API → Your data
                                  |
                                  └→ Knowledge Base → Platform docs & code

The AI assistant uses the MCP tools to query your Isabl instance in real time, and the built-in knowledge base to understand Isabl concepts, API patterns, and best practices.

Knowledge Tree

The knowledge base is built from 347 documents extracted from Isabl's source code, documentation, and API specifications. Browse the interactive visualization:

Explore the Knowledge Tree →

Configuration

Example Usage

#### Example Queries

1. Common queries with desired output format:

<img width="740" height="406" alt="Image" src="https://github.com/user-attachments/assets/43ce5f73-aa1f-4e98-9ce6-2ccc2cb250f8" />

1. Multi-step queries:

<img width="887" height="606" alt="Image" src="https://github.com/user-attachments/assets/95fcfa10-c9f0-4931-af12-3f548aa12a89" /> <img width="888" height="718" alt="Image" src="https://github.com/user-attachments/assets/668528e3-8d35-4733-80e2-bfd85e90f467" />

1. Help to write Isabl apps:

<img width="766" height="1323" alt="Image" src="https://github.com/user-attachments/assets/f5b7540f-6d01-4f07-a18e-7fe582af68a9" />

#### Example Commands

Browse available commands: /isabl

<img width="888" height="434" alt="Image" src="https://github.com/user-attachments/assets/561abe2d-466d-4cdd-b81c-887f57e010d0" />

/isabl:isabl-monitor-analyses check the status of RNA apps in project 455

<img width="886" height="826" alt="Image" src="https://github.com/user-attachments/assets/1db721d5-8019-4540-9b83-e488e588aec9" /> <img width="891" height="498" alt="Image" src="https://github.com/user-attachments/assets/88504c28-55e5-4e66-a063-2d3c67e5f731" />

Development

cd mcp-server
uv sync --dev
uv run pytest
uv run ruff check isabl_mcp/  # lint
uv run mcp dev isabl_mcp/server.py  # test with MCP Inspector
uv run isabl-mcp           # start server locally

Contributing

1. Add tools in mcp-server/isabl_mcp/tools/, register in server.py, add tests
2. Add skills as skills/isabl-*.md (YAML frontmatter + workflow steps)
3. Use ruff for linting, type hints for Python
4. Submit a PR

Related

• Isabl Documentation
• isabl_cli — Python SDK
• Isabl Paper

License

MIT