MCPDog 🐕 — MCP 服务器统一管理网关（团队维护版）

一次配置，统一管理所有 MCP 服务器

MCPDog 是一个 MCP（Model Context Protocol）服务器统一管理网关：把多个 MCP 子服务器聚合成一个统一入口，供 Claude Desktop、Cursor、Claude Code 等 MCP 客户端使用。由 SIE 运维团队基于上游开源项目维护，包含 Windows 平台兼容修复与 Web 界面汉化等本地化改进。

🏗️ 架构概览

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP 客户端:   │    │   MCP 客户端:   │    │   MCP 客户端:   │
│    (Claude)     │    │    (Cursor)     │    │  (Claude Code)  │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │         MCPDog             │
                    │    （统一入口 + 智能路由）  │
                    └────────────┬──────────────┘
                                 │
          ┌──────────────────────┼──────────────────────┐
          │                      │                      │
    ┌─────▼─────┐         ┌──────▼──────┐         ┌─────▼─────┐
│ db-tools    │         │  itsm-tools │         │ playwright │
└───────────┘         └─────────────┘         └───────────┘

核心价值

• 🔗 一次配置：客户端只连 MCPDog 一个入口，不用逐个配置子服务器
• 🔄 统一界面：所有子服务器的工具合并成一张清单暴露给客户端
• ⚡ 智能路由：MCPDog 自动把工具调用路由到对应的子服务器
• 🌐 多传输协议：子服务器支持 stdio / HTTP SSE / Streamable HTTP 三种接入方式
• 📊 集中管理：Web 管理界面可视化增删改查服务器、启停、工具开关
• 🛡️ 故障隔离：单个子服务器挂掉不影响其他子服务器和整体入口

🚀 快速开始

前置要求：Node.js ≥ 18。无需安装，npx 直接启动：

npx @keysqiu/mcpdog@latest daemon start --web-port 38881

启动后浏览器打开 http://localhost:38881 即可看到 Web 管理界面，在界面里添加并管理子服务器。

客户端接入（以 Claude Code 为例）

在 MCP 客户端配置中加入：

{
  "mcpServers": {
    "mcpdog": {
      "command": "npx",
      "args": ["@keysqiu/mcpdog@latest"]
    }
  }
}

客户端连的是 MCPDog 聚合入口，前提是 daemon 已启动并配好子服务器。

📖 常用命令

npx @keysqiu/mcpdog@latest status              # 查看整体状态
npx @keysqiu/mcpdog@latest daemon start --web-port 38881   # 启动 daemon + Web 界面
npx @keysqiu/mcpdog@latest daemon stop         # 停止 daemon
npx @keysqiu/mcpdog@latest daemon restart      # 重启 daemon（版本更新后直接重跑 start 也会自动升级重启）
npx @keysqiu/mcpdog@latest config list          # 列出已配置的服务器
npx @keysqiu/mcpdog@latest config add my-server "npx @some/mcp-server@latest" --auto-detect
                                                # 添加子服务器（自动识别传输协议）
npx @keysqiu/mcpdog@latest config remove old-server       # 移除子服务器
npx @keysqiu/mcpdog@latest diagnose --health-check        # 健康检查
npx @keysqiu/mcpdog@latest diagnose --fix                # 自动修复常见问题

🖥️ Web 管理界面

• 服务器列表：连接状态、工具数一目了然，支持启用/禁用、编辑、删除
• 工具管理：按服务器查看全部工具，逐个开关（白名单/黑名单两种模式）
• 服务器日志：实时查看子服务器的 stdout/stderr
• 客户端配置：一键生成 Claude Desktop / Cursor 的接入配置

🧩 子服务器配置示例

配置文件位于 ~/.mcpdog/mcpdog.config.json，也可全部在 Web 界面操作：

{
  "servers": {
    "my-stdio-server": {
      "name": "my-stdio-server",
      "enabled": true,
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@some/mcp-server"],
      "env": { "API_KEY": "xxx" }
    },
    "my-http-server": {
      "name": "my-http-server",
      "enabled": true,
      "transport": "streamable-http",
      "url": "http://127.0.0.1:61123/mcp"
    }
  }
}

工具冲突处理

多个子服务器存在同名工具时，MCPDog 自动将工具重命名为 服务器名-工具名（如 db-tools-db_query），调用时自动剥前缀转发到原服务器，客户端无感知。

🐛 常见问题

服务器连不上，提示 initialize timeout Windows 平台下全局命令（npx/npm 等）是 .cmd 批处理脚本，本版本已通过 cross-spawn 修复该兼容问题（上游版本在 Windows 上会出现 stdio 子服务器全部连接超时）。

查看运行日志

npx @keysqiu/mcpdog@latest daemon logs

工具不可见 / 缺失

npx @keysqiu/mcpdog@latest detect --all
npx @keysqiu/mcpdog@latest config show my-server

🏢 关于本仓库

• 本仓库由 SIE 运维团队 维护，在上游开源项目基础上做了本地化改进
• 上游原始项目：MIT 协议开源，版权归原作者所有（详见 LICENSE 声明）

📄 许可证

MIT License — 详见 LICENSE