Polyagent MCP

🚀 Polyagent MCP

Polyagent MCP 是一个 MCP 服务器，它能将 Claude Code 代理集成到 Codex、Gemini CLI 等 AI 代码编写助手之中。借助该服务器，任何兼容 MCP 的客户端都能直接使用现有的 .claude/agents/ 定义，无需额外配置。

🚀 快速开始

安装

使用 uvx 快速启动（推荐）

可直接从 GitHub 运行，无需克隆仓库：

# 默认标准输入输出传输
uvx --from git+https://github.com/execveat/polyagent-mcp polyagent-mcp

# 自定义端口的 HTTP 传输
uvx --from git+https://github.com/execveat/polyagent-mcp polyagent-mcp --transport http --port 8000

本地开发

克隆仓库并安装以进行开发：

git clone https://github.com/execveat/polyagent-mcp.git
cd polyagent-mcp
uv sync

可通过以下任一方式在本地运行：

# 使用控制台脚本
uv run polyagent-mcp

# 使用 fastmcp CLI（用于开发时自动重载）
uv run fastmcp dev polyagent_mcp.server:mcp

配置

Codex

在 Codex 配置中添加以下内容，超时时间至少设置为 15 分钟：

[mcp_servers.agents]
command = "uvx"
args = ["--from", "git+https://github.com/execveat/polyagent-mcp", "polyagent-mcp"]
tool_timeout_sec = 900

本地开发时（如果你已克隆仓库）：

[mcp_servers.agents]
command = "uv"
args = ["--directory", "/path/to/polyagent-mcp", "run", "polyagent-mcp"]
tool_timeout_sec = 900

重要提示：

• 使用 tool_timeout_sec = 900 或更高的值。较低的超时时间会导致代理调用过早失败。
• uvx 方法会自动从 GitHub 安装和更新。
• 本地开发时，将 /path/to/polyagent-mcp 替换为你实际的克隆路径。

Gemini CLI

在 settings.json 中添加以下内容：

{
  "mcpServers": {
    "agents": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/execveat/polyagent-mcp",
        "polyagent-mcp"
      ],
      "timeout": 900000
    }
  }
}

本地开发时：

{
  "mcpServers": {
    "agents": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/polyagent-mcp",
        "run",
        "polyagent-mcp"
      ],
      "timeout": 900000
    }
  }
}

重要提示：

• 超时时间以毫秒为单位：900000 即 15 分钟。
• 本地开发时，将 /path/to/polyagent-mcp 替换为你实际的克隆路径。

环境变量

可通过环境变量进行配置（均为可选）：

• POLYAGENT_MCP_DIR – 包含代理 Markdown 文件的目录（默认：.claude/agents）
• POLYAGENT_MCP_CONFIG – 用于覆盖运行器/代理配置的可选 YAML/JSON 文件
• POLYAGENT_MCP_WORKSPACE – 代理执行的工作目录
• POLYAGENT_MCP_TIMEOUT – 默认超时时间（秒）（默认：900）
• POLYAGENT_MCP_LOG_LEVEL – Python 日志级别（默认：INFO）
• POLYAGENT_MCP_DEBUG – 启用 FastMCP 调试模式

使用

配置完成后，你的 MCP 客户端将自动发现 .claude/agents/ 中的所有代理：

1. 列出可用代理：查看 resource://agents/manifest 或使用客户端的工具列表。
2. 查看代理说明：在委托任务前，阅读 agent://<代理名称>。
3. 调用代理：调用以代理命名的工具（例如，commit-agent）。

工具调用示例：

{
  "tool": "commit-agent",
  "arguments": {
    "task": "Review and commit the changes with an appropriate message",
    "context": "Fixed authentication bug in login flow"
  }
}

可选参数：

• runner – 强制使用特定的 CLI（codex、claude、gemini）
• model – 运行器特定的模型别名
• timeout_seconds – 延长长时间操作的超时时间

✨ 主要特性

为何存在此项目

拥有 Claude Code 代理的团队希望使用 Codex 或 Gemini 的同事能够复用相同的代理，而无需进行任何移植工作。Polyagent MCP 为使用 Codex 或 Gemini 且可能无法访问 Claude Code 的贡献者提供了零配置体验，使他们能够享受与 Claude Code 相同的基于代理的工作流程。该项目专为那些已经在设计 Claude Code 优化子代理方面投入大量精力的项目而设计，可直接作为这些项目的一项功能使用。

工作原理

在 Codex 或 Gemini 中运行此 MCP 服务器时，它会通过单独的 CLI 会话生成代理，使其表现与 Claude Code 代理类似，具备以下优点：

• 上下文优化：由于代理在单独的上下文中初始化，主进程使用的上下文更少，且仅返回重要信息，而非所有中间输出和思考标记。
• 性能提升：每个代理都可以拥有自己的知识和规则。由于在新会话中运行，与将相同指令交给承担多项职责的单个 AI 代理相比，通常能更好地遵循提示（单一职责原则）。

📚 详细文档

要求

• Python 3.10 及以上版本
• 至少安装以下其中一个 CLI：codex、claude 或 gemini
• 存在包含代理定义的 .claude/agents/ 目录

📄 许可证

本项目采用 MIT 许可证。