Galaxy MCP Server - Python Implementation

This is the Python implementation of the Galaxy MCP server, providing a Model Context Protocol server for interacting with Galaxy instances.

Features

• Complete Galaxy API integration through BioBlend
• Optional OAuth login flow for HTTP deployments
• Interactive Workflow Composer (IWC) integration
• FastMCP2 server with remote deployment support
• Type-annotated Python codebase

Requirements

• Python 3.10+
• FastMCP 2.3.0+

Installation

From PyPI (Recommended)

# Install from PyPI
pip install galaxy-mcp

# Or using uv (recommended)
uvx galaxy-mcp

From Source

# Clone the repository
git clone https://github.com/galaxyproject/galaxy-mcp.git
cd galaxy-mcp/mcp-server-galaxy-py

# Install with uv (recommended)
uv sync --all-extras

Configuration

At minimum the server needs to know which Galaxy instance to target:

export GALAXY_URL="https://usegalaxy.org.au/"

How you authenticate depends on your transport:

• Stdio / long-lived sessions – provide an API key:

  export GALAXY_API_KEY="your-api-key"
  

• HTTP / OAuth – configure the public URL that users reach and a signing secret for session tokens. The server mints short-lived Galaxy API keys on behalf of each user.

  GALAXY_MCP_SESSION_SECRET is required whenever GALAXY_MCP_PUBLIC_URL is set; the server refuses to start without it. Generate it once with openssl rand -hex 32 and store it — the same value must be used on every restart and every replica, since it is the key that encrypts session tokens. A fresh secret invalidates every token issued under the old one.

  export GALAXY_MCP_PUBLIC_URL="https://mcp.example.com"
  export GALAXY_MCP_SESSION_SECRET="<your stored secret>"
  

  Optionally set GALAXY_MCP_CLIENT_REGISTRY to control where OAuth client registrations are stored.

  For non-OAuth HTTP clients, connect(url=..., api_key=...) stores Galaxy credentials per MCP session rather than globally. Clients normally preserve MCP sessions by default, which allows multiple users to share the same MCP server while keeping their Galaxy credentials isolated.

You can also steer the transport with GALAXY_MCP_TRANSPORT (stdio, streamable-http, or sse). All variables can be placed in a .env file for convenience.

Usage

Quick Start with uvx

# Local stdio transport (no network listener)
uvx galaxy-mcp

# Remote/browser clients with HTTP + OAuth
export GALAXY_URL="https://usegalaxy.org.au/"
export GALAXY_MCP_PUBLIC_URL="https://mcp.example.com"
export GALAXY_MCP_SESSION_SECRET="$(openssl rand -hex 32)"
uvx galaxy-mcp --transport streamable-http --host 0.0.0.0 --port 8000

Installed CLI

pip install galaxy-mcp
galaxy-mcp --transport streamable-http --host 0.0.0.0 --port 8000

If --transport is omitted the server defaults to stdio and reads/writes MCP messages via stdin/stdout.

Working from a checkout

uv sync
uv run galaxy-mcp --transport streamable-http --host 0.0.0.0 --port 8000

See USAGE_EXAMPLES.md for detailed tool usage patterns.

Tool discovery mode (experimental)

Galaxy MCP exposes 30+ @mcp.tool registrations, which costs tokens on every turn for agents that only ever use a handful. --discovery-mode code (also honored via GALAXY_MCP_DISCOVERY_MODE=code) collapses the whole catalog into three meta-tools:

• search -- BM25 search over tool names and descriptions
• get_schema -- fetch the full schema for specific tools
• run_galaxy_tool -- execute any tool by name

pip install 'galaxy-mcp[code-mode]'   # pulls in pydantic-monty sandbox
galaxy-mcp --discovery-mode code

The code-mode extra installs pydantic-monty, the sandboxed Python interpreter that backs run_galaxy_tool. Without it the server still starts in full mode but raises a clear error if --discovery-mode code is requested.

Default is full, which keeps the existing catalog unchanged. CodeMode is useful when you want to keep the agent's context lean and are willing to trade a few extra turns (search -> schema -> execute) per tool call. It's built on FastMCP's experimental CodeMode transform, so the API may shift before it stabilizes.

The server also ships agent-facing usage guidance via the MCP instructions field (returned during the initial handshake). It explains the typical workflow, the difference between MCP tools and Galaxy tools (e.g. FastQC isn't an MCP tool -- find it via search_tools_by_name), and -- when code mode is active -- how to use run_galaxy_tool and call_tool. Agents that respect the instructions field will read this without you having to prompt them.

Available MCP Tools

The Python implementation provides the following MCP tools:

• connect: Establish connection to a Galaxy instance
• search_tools_by_name: Find Galaxy tools by name
• get_tool_details: Retrieve detailed tool information
• run_tool: Execute a Galaxy tool with parameters
• get_tool_panel: Retrieve the Galaxy tool panel structure
• get_tool_run_examples: Retrieve XML-defined test lessons that show how to run a tool
• get_tool_input_template: Returns a ready-to-fill inputs skeleton (with placeholders) plus the parameter schema for a tool, to build correct run_tool inputs
• get_user: Get current user information
• get_histories: List available Galaxy histories
• list_history_ids: Get simplified list of history IDs and names
• get_history_details: Get detailed information about a specific history
• upload_file: Upload local files to Galaxy
• upload_file_from_url: Upload files from URLs to Galaxy
• list_workflows: List available workflows in Galaxy instance
• get_workflow_details: Get detailed information about a specific workflow
• invoke_workflow: Execute/run a workflow with specified inputs
• cancel_workflow_invocation: Cancel a running workflow invocation
• get_invocations: View workflow executions
• get_iwc_workflows: Access Interactive Workflow Composer workflows
• search_iwc_workflows: Search IWC workflows by keywords
• import_workflow_from_iwc: Import an IWC workflow to Galaxy

Testing

The project includes a comprehensive test suite using pytest with mock-based testing.

Running Tests

# Install test dependencies
uv pip install -r requirements-test.txt

# Run all tests
uv run pytest

# Run with coverage report
uv run pytest --cov=main --cov-report=html

# Run specific test file
uv run pytest tests/test_history_operations.py

# Run tests with verbose output
uv run pytest -v

Test Structure

Tests are organized by functionality:

• test_connection.py - Galaxy connection and authentication
• test_history_operations.py - History-related operations
• test_dataset_operations.py - Dataset upload/download
• test_tool_operations.py - Tool search and execution
• test_workflow_operations.py - Workflow import and invocation
• test_integration.py - End-to-end scenarios

See tests/README.md for more details on the testing strategy.

Development

Code Style Guidelines

• Use Python 3.10+ features
• Employ type hints where appropriate
• Follow PEP 8 style guidelines
• Use ruff for code formatting and linting
• All code should pass type checking with mypy

Development Setup

# Install development dependencies
make install-dev

# Set up pre-commit hooks (required for contributing)
uv run pre-commit install

Pre-commit hooks will automatically format your code and run linting checks when you commit. All contributors should install these hooks to maintain consistent code quality.

Development Commands

We use a Makefile for consistent development commands:

# Show all available commands
make help

# Install dependencies
make install       # Install all dependencies

# Code quality
make lint          # Format code and run all checks

# Testing
make test          # Run tests with coverage

# Building
make clean         # Clean build artifacts
make build         # Build distribution packages

# Running
make run           # Run the MCP server
make dev           # Run FastMCP2 dev server

Using uv directly

All commands can also be run directly with uv:

# Install dependencies
uv sync --all-extras

# Format and lint code
uv run pre-commit run --all-files

# Run tests with coverage
uv run pytest --cov=galaxy_mcp --cov-report=html

# Update dependencies
uv lock --upgrade

Cross-version Testing

Test across multiple Python versions using tox:

# Test on all supported Python versions
tox

# Test on specific version
tox -e py312

# Run only linting
tox -e lint

# Run type checking
tox -e type

Pre-commit Hooks

The project uses pre-commit hooks for automatic code quality checks:

# Install pre-commit hooks (one-time setup)
uv run pre-commit install

# Run pre-commit manually on all files
uv run pre-commit run --all-files

# Skip pre-commit for a single commit (not recommended)
git commit --no-verify

Pre-commit runs automatically on git commit and includes:

• Code formatting with ruff
• Linting with ruff
• Trailing whitespace removal
• File cleanup (EOF, YAML/JSON/TOML validation)
• Large file detection
• Merge conflict detection

License

MIT