galaxy-mcp

Galaxy MCP 服务

本项目为 Galaxy 生物信息学平台提供 Model Context Protocol（MCP）服务。它支持 AI 助手和其他客户端连接到 Galaxy 实例、搜索和执行工具、管理工作流，以及使用 Galaxy 生态系统的其他功能。

项目概览

此代码库包含两套相互独立的实现，它们提供相同的 Galaxy 操作集，并遵循同一份契约：

• python/ -- Python MCP 服务，通过 PyPI 发布为 galaxy-mcp。它通过 BioBlend 连接到 Galaxy。请参阅 Python README。
• typescript/ -- pnpm 工作区，通过 npm 发布为 @galaxyproject/galaxy-ops、galaxy-cli 和 galaxy-mcp：包含一个不依赖框架的核心（galaxy-ops），以及基于它构建的命令行和 stdio MCP 服务。请参阅 TypeScript README。
• contract/ -- 两套实现共同遵循的内容：Python 接口清单、通过两者重放的黄金结果、Galaxy 内置服务的快照，以及已知差异的注册表。请参阅 契约 README。

两套实现旨在保持一致：同一操作在两者中应具有相同的名称和含义。不过，它们仍是独立的代码库，发布周期也各自独立，因此每份 README 都列出了对应实现实际提供的操作——请阅读你所使用实现的 README。

ROADMAP.md 说明了为何有两套实现、它们与 Galaxy 内置 MCP 服务的关系，以及后续计划。PARITY.md 是生成的、由 CI 检查的差异记录。

主要功能

• 连接 Galaxy：使用 URL 和 API 密钥连接到任意 Galaxy 实例
• OAuth 登录（可选）：提供基于浏览器的登录方式，将凭据换取为临时 Galaxy API 密钥
• 服务信息：获取全面的服务详情，包括版本、配置和功能
• 工具管理：搜索工具目录、查看工具的输入项并执行 Galaxy 工具
• 用户自定义工具：创建、列出、运行和停用权限受限的用户自定义工具
• 工作流集成：从星际工作流委员会（IWC）查找并导入工作流，然后调用工作流并跟踪其调用情况
• 历史记录操作：管理 Galaxy 历史记录、数据集和集合，并检查其背后的作业
• 文件管理：从本地存储或 URL 上传文件到 Galaxy，并下载结果
• 页面：读取和编写 Galaxy 风格的 Markdown 页面——包括附加到历史记录的笔记本和独立报告——以及查看其修订历史
• 经过验证的容器推荐（可选）：根据一组 conda 软件包解析真实的 quay.io/biocontainers 镜像，而非猜测镜像——请参阅可选扩展
• 基于模拟的测试套件：默认测试套件完全使用模拟的 Galaxy 响应运行，无需服务；另有一个针对实时 Galaxy 的独立测试套件，需显式启用，且未配置凭据时会跳过

可选扩展

container-recommend

启用 recommend_biocontainer 工具，可根据一组 conda 软件包解析出经过验证的 quay.io/biocontainers 镜像。编写用户自定义工具时，需要指定一个容器，而虚构的镜像标签是 UDT 通过验证后在运行时因 manifest unknown 错误而失败的最常见原因。此工具封装了 galaxy.tool_util.deps.mulled.recommend——也就是 Galaxy 自带的自定义工具 Agent 使用的同一解析器（在 Galaxy 26.1 中新增，galaxyproject/galaxy#22981）——因此会对照 quay.io 检查镜像，而非凭空编造。

它是额外功能，而非硬性依赖，因为 galaxy-tool-util 会引入 lxml 和 conda-package-streaming，而此服务上的其他工具都无需它们即可运行。只有安装此额外依赖后，才会注册该工具，因此标准安装不会公开此工具。

uvx --from 'galaxy-mcp[container-recommend]' galaxy-mcp
# or, for a local checkout:
cd python && uv sync --extra container-recommend

安装后，也可以通过独立的 CLI 使用同一解析器： mulled-recommend samtools=1.17。

code-mode

将整个工具目录整合为三个元工具——search、get_schema 和 run_galaxy_tool——这样 Agent 只有在决定使用某个工具时才需要获取其架构。此额外依赖会引入 pydantic-monty，这是用于运行所提交代码的沙盒解释器。如果未安装此额外依赖，服务仍会启动，但请求代码模式时会报错，而不会静默降级。

uvx --from 'galaxy-mcp[code-mode]' galaxy-mcp --discovery-mode code

有关这种权衡带来的好处，请参阅 Python README 中的工具发现模式。

快速开始

galaxy-mcp CLI 同时支持 stdio（本地）和 HTTP 传输。选择适合你客户端的配置：

# Stdio transport (default) – great for local development tools
uvx galaxy-mcp

# HTTP transport with OAuth (for remote/browser clients)
# Generate the session secret ONCE (`openssl rand -hex 32`) and store it. Every
# restart and every replica must use the same value, or tokens issued earlier --
# or by another replica -- stop decrypting.
export GALAXY_URL="https://usegalaxy.org.au/"          # Target Galaxy instance
export GALAXY_MCP_PUBLIC_URL="https://mcp.example.com" # Public base URL for OAuth redirects
export GALAXY_MCP_SESSION_SECRET="<your stored secret>"
uvx galaxy-mcp --transport streamable-http --host 0.0.0.0 --port 8000

使用 stdio 运行时，可以通过环境变量提供长期有效的凭据：

export GALAXY_URL="https://usegalaxy.org/"
export GALAXY_API_KEY="your-api-key"

对于 OAuth 流程，服务会按需将用户凭据换成短期有效的 Galaxy API 密钥，因此通常无需设置 GALAXY_API_KEY。

对于非 OAuth HTTP 客户端，connect(url=..., api_key=...) 会按 MCP 会话而非全局存储 Galaxy 凭据，且 URL 必须是操作员允许的地址（GALAXY_URL 或 GALAXY_MCP_EXTRA_ALLOWED_URLS）。这样可以隔离各个会话，但这并非身份验证：HTTP 传输默认绑定到 127.0.0.1，除非传入 --allow-unauthenticated，否则拒绝为非环回地址提供服务，并且会禁用访问服务端文件系统的工具。请参阅通过 HTTP 提供服务。

其他安装方式

# Install from PyPI
pip install galaxy-mcp

# Run (stdio by default)
galaxy-mcp

# Or from source using uv
cd python
uv sync
uv run galaxy-mcp --transport streamable-http --port 8000

容器用法

镜像已发布到 GitHub Container Registry，地址为 ghcr.io/galaxyproject/galaxy-mcp。 使用 :latest（默认），或固定到某个发行版，例如 :1.10.0。

已发布的镜像默认使用 stdio 传输（不启动 HTTP 监听器）：

docker run --rm -it \
  -e GALAXY_URL="https://usegalaxy.org/" \
  -e GALAXY_API_KEY="your-api-key" \
  ghcr.io/galaxyproject/galaxy-mcp

使用 OAuth + HTTP：

# Generate once and keep it -- do NOT inline `openssl rand` here, or each
# container start mints a key that invalidates every token issued before it.
export GALAXY_MCP_SESSION_SECRET="<your stored secret>"

docker run --rm -it -p 8000:8000 \
  -e GALAXY_URL="https://usegalaxy.org.au/" \
  -e GALAXY_MCP_TRANSPORT="streamable-http" \
  -e GALAXY_MCP_PUBLIC_URL="https://mcp.example.com" \
  -e GALAXY_MCP_SESSION_SECRET \
  ghcr.io/galaxyproject/galaxy-mcp

连接到 Claude Desktop

• 确保 GalaxyMCP 使用 uvx galaxy-mcp 运行
• 将 export GALAXY_URL=https://usegalaxy.org 添加到你的 .bashrc（或同类配置文件）
• 下载并安装 claude desktop
• 前往 Settings -> Developer -> Edit Config
• 将以下内容添加到 claude_desktop_config.json

{
  "mcpServers": {
    "galaxy-mcp": {
      "command": "uvx",
      "args": ["galaxy-mcp"],
      "env": {
        "GALAXY_URL": "https://usegalaxy.org",
        "GALAXY_API_KEY": "SECRETS"
      }
    }
  }
}

• 在开发者菜单下，现在应该能看到 galaxy-mcp 正在运行（可能需要重启 Claude desktop）
• 向 Claude 提示“你能连接到 galaxy 吗”
• 如果你没有提供可选的环境变量配置，系统会询问连接详情，你可以这样提供：“使用我的 Galaxy API 密钥：XXXXXXX”
• 与 Claude 对话，操作你的 galaxy 实例，例如：“总结一下我的历史记录”

开发指南

具体说明和文档请参阅 Python 实现 README。

许可证

MIT