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.

  export GALAXY_MCP_PUBLIC_URL="https://mcp.example.com"
  export GALAXY_MCP_SESSION_SECRET="$(openssl rand -hex 32)"
  

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

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.

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