1MCP Agent

简体中文

English

简体中文

English

主题

Claude Desktop 集成 ​

了解如何使用两种不同的方法将您的 1MCP 服务器与 Claude Desktop 集成：本地配置整合（为简单起见，建议使用）和远程自定义连接器（用于高级用例）。

集成方法 ​

1. 本地配置整合（推荐） ​

最简单的方法是使用 1MCP 作为本地代理，将您现有的 MCP 服务器整合到 Claude Desktop 的配置中。此方法：

  • 使用 1MCP 代理来桥接 STDIO 和 HTTP 传输
  • 自动配置 Claude Desktop 以使用 1MCP 代理
  • 保留您现有的 MCP 服务器配置
  • 通过全局预设启用服务器筛选
  • 在后台运行 1MCP HTTP 服务器

2. 远程自定义连接器（高级） ​

对于高级场景，您可以使用 Claude Desktop 的自定义连接器功能并通过 HTTP 或 SSE 传输连接到远程 1MCP 服务器。此方法：

  • 需要公共 HTTPS URL（隧道/反向代理）
  • 支持 OAuth 身份验证
  • 启用对集中式 1MCP 服务器的远程访问
  • 适用于团队/企业部署

为什么将 1MCP 与 Claude Desktop 一起使用？ ​

  • 统一访问：通过一个端点访问多个 MCP 服务器
  • 服务器筛选：使用预设控制可用的服务器
  • 集中管理：在一个地方管理所有 MCP 服务器
  • 热重载：无需重新启动 Claude Desktop 即可添加/删除服务器
  • 预设切换：轻松切换不同的服务器配置

快速路径 ​

选择你的方法 ​

  • 本地（推荐）：1MCP 代理桥接 STDIO↔HTTP，支持基于预设的筛选
  • 远程（高级）：通过 HTTPS 暴露 1MCP 并添加自定义连接器

本地设置（推荐） ​

本地方法使用两个组件：一个运行中的 1MCP HTTP 服务器和一个桥接到 Claude Desktop STDIO 传输的代理。

bash
# 1. 可选：先添加一些服务器（用标签进行筛选）
npx -y @1mcp/agent mcp add context7 --tags=documentation,docs -- npx -y @upstash/context7-mcp
npx -y @1mcp/agent mcp add sequential --tags=thinking,analysis -- npx -y @modelcontextprotocol/server-sequential-thinking

# 2. 创建用于筛选服务器访问的预设（推荐）
npx -y @1mcp/agent preset create claude-desktop --filter "documentation OR thinking"

# 3. 在后台启动 1MCP HTTP 服务器
npx -y @1mcp/agent serve &

# 4. 将 Claude Desktop 整合为使用 1MCP 代理
npx -y @1mcp/agent app consolidate claude-desktop --dry-run  # 预览
npx -y @1mcp/agent app consolidate claude-desktop

然后重启 Claude Desktop。会自动创建备份；可随时恢复：

bash
npx -y @1mcp/agent app backups claude-desktop
npx -y @1mcp/agent app restore claude-desktop

全局预设配置 ​

对于服务器筛选，代理命令使用全局预设。您可以在配置 Claude Desktop 时指定要使用的预设：

bash
# 使用特定预设测试
npx -y @1mcp/agent proxy --preset claude-desktop

这样可以启用适用于所有 Claude Desktop 对话的全局服务器筛选。

远程自定义连接器（高级） ​

  1. 启动服务器
bash
npx -y @1mcp/agent serve --transport http --port 3001 --external-url https://your-domain.com  # 开发
npx -y @1mcp/agent serve --transport http --port 3001 --enable-auth --external-url https://your-domain.com  # 生产

服务路径：/mcp（Streamable HTTP）、/sse + /messages（SSE）、/oauth（OAuth）、/health（健康检查）。

  1. 通过 HTTPS 暴露服务器
  • ngrok：ngrok http 3001 → 使用 https://<id>.ngrok-free.app/mcp
  • 反向代理：
    • nginx：将 location / 代理到 http://localhost:3001（HTTP/1.1，关闭缓冲）
    • Caddy：reverse_proxy localhost:3001
    • Traefik：为主机创建路由 → 服务 1mcp（端口 3001）
  1. 在 Claude Desktop 中添加连接器
  • 名称：任意（例如“1mcp”）
  • URL：你的公共 https://.../mcp
  • 可选：OAuth Client ID/Secret

注意：OAuth 2.1 会校验发行者（issuer）URL。务必将 --external-url 设置为你的公共来源（例如 https://your-domain.com 或 https://abc123.ngrok-free.app）。

  • 必须使用 HTTPS
  • 不要包含路径（不要带 /mcp）
  • 必须与 Claude Desktop 使用的来源完全一致

步骤 2：在 Claude Desktop 中添加自定义连接器 ​

  1. 打开 Claude Desktop 设置

    • 点击 Claude Desktop 中的个人资料/设置
    • 前往“Connectors”或相关连接器管理处

  2. 添加自定义连接器

    • 点击“Add custom connector”
    • 你会看到类似如下的对话框：

步骤 1：添加自定义连接器对话框

  1. 输入连接详情

    • Name：为连接器输入名称（例如“1mcp”）
    • URL：输入公共 HTTPS URL：
      • 使用 ngrok：https://abc123.ngrok-free.app/mcp
      • 使用反向代理：https://your-domain.com/mcp
    • OAuth Client ID（可选）：若启用身份验证
    • OAuth Client Secret（可选）：若启用身份验证

  2. 确认信任

    • 阅读安全警告
    • 点击“Add”确认信任该连接器

步骤 3：验证连接 ​

添加连接器后，你应能看到 1MCP 提供的工具：

步骤 2：1MCP 提供的可用工具

实际显示的工具取决于你的 1MCP 实例中已配置的 MCP 服务器，常见包括：

  • Context7 文档工具
  • 顺序思维工具
  • Playwright 浏览器自动化
  • 以及你添加的其他 MCP 服务器

步骤 4：开始使用工具 ​

连接后，1MCP 工具会出现在 Claude Desktop 的聊天界面中：

步骤 3：聊天中可用的工具

你现在可以在与 Claude 的对话中直接使用这些工具。

💡 提示：若某服务显示 “Awaiting OAuth”，访问服务器的 OAuth 面板 https://your-domain.com/oauth，点击授权后再在 Claude Desktop 重试。

服务器快速配置 ​

bash
# 启动
npx -y @1mcp/agent serve --transport http --port 3001 --external-url https://your-domain.com

# 启用身份验证（生产环境推荐）
npx -y @1mcp/agent serve --transport http --port 3001 --enable-auth --external-url https://your-domain.com

# 筛选运行时暴露的服务器
npx -y @1mcp/agent serve --transport http --port 3001 --filter "context7,sequential" --external-url https://your-domain.com

# 绑定到所有网卡（置于反向代理后）
npx -y @1mcp/agent serve --transport http --port 3001 --host 0.0.0.0 --external-url https://your-domain.com

身份验证 ​

  • 启用：npx -y @1mcp/agent serve --transport http --port 3001 --enable-auth
  • 如需，在 Claude Desktop 中配置 Client ID/Secret；OAuth 流程自动处理

故障排除 ​

本地配置问题 ​

整合后工具未出现 ​

症状：整合完成但 Claude Desktop 中未显示工具。

解决方案：

  1. 重启 Claude Desktop：整合后务必完全重启

  2. 检查配置：验证整合是否正确

    bash
    # 检查生成的配置
cat "~/Library/Application Support/Claude/claude_desktop_config.json"

  3. 测试 1MCP 组件：确认 HTTP 服务器和代理都正常工作

    bash
    # 检查服务器状态
npx -y @1mcp/agent mcp status

# 启动 HTTP 服务器（如果未运行）
npx -y @1mcp/agent serve &

# 在另一个终端中测试代理命令
npx -y @1mcp/agent proxy --log-level=debug

“整合失败”错误 ​

症状：整合命令执行报错。

解决方案：

  1. 使用 --force：跳过连通性校验

    bash
    npx -y @1mcp/agent app consolidate claude-desktop --force

  2. 检查权限：确认对 Claude Desktop 配置目录的写入权限

    bash
    ls -la "~/Library/Application Support/Claude/"

  3. 手动清理：若整合只做了一半

    bash
    # 从备份还原
npx -y @1mcp/agent app restore claude-desktop

# 或强制重新整合
npx -y @1mcp/agent app consolidate claude-desktop --force

"配置备份失败"错误 ​

症状：无法创建现有配置的备份。

解决方案：

  1. 检查磁盘空间

  2. 检查权限：验证备份目录写入权限

  3. 强制模式：在必要时无备份继续（谨慎）

    bash
    npx -y @1mcp/agent app consolidate claude-desktop --force --backup-only

代理连接问题 ​

症状：Claude Desktop 显示连接错误或整合后工具未出现。

解决方案：

  1. 验证 HTTP 服务器正在运行：代理需要运行中的 1MCP HTTP 服务器

    bash
    # 检查服务器是否正在运行
curl http://localhost:3050/health

# 启动服务器（如果未运行）
npx -y @1mcp/agent serve &

  2. 直接测试代理命令：验证代理可以连接到服务器

    bash
    # 使用调试日志测试代理
npx -y @1mcp/agent proxy --log-level=debug

  3. 验证预设和标签：确保服务器具有与预设筛选器匹配的标签

    bash
    # 列出服务器及其标签
npx -y @1mcp/agent mcp list

# 检查预设包含哪些服务器
npx -y @1mcp/agent preset show claude-desktop

  4. 使用预设测试代理：验证代理与指定的预设一起工作

    bash
    # 使用 Claude Desktop 中使用的预设测试代理
npx -y @1mcp/agent proxy --preset claude-desktop --log-level=debug

服务器发现问题 ​

症状：代理无法找到运行中的 1MCP HTTP 服务器。

解决方案：

  1. 检查常用端口：代理默认扫描端口 3050、3051、3052

    bash
    # 查看常用端口上运行的内容
netstat -an | grep -E ':(3050|3051|3052)'

  2. 手动指定服务器 URL：覆盖自动发现

    bash
    # 使用特定服务器 URL 测试代理
npx -y @1mcp/agent proxy --url http://localhost:3050/mcp

  3. 检查防火墙：确保本地防火墙没有阻止连接

远程自定义连接器问题 ​

“无法连接”错误 ​

症状：添加连接器时 Claude Desktop 显示连接失败。

解决方案：

  1. 检查服务器状态

    bash
    npx -y @1mcp/agent mcp status  # 查看服务器是否已运行

  2. 验证 URL：确保 URL 正确且可访问

    bash
    # 健康检查端点在 /health
curl https://your-domain.com/health

  3. 检查防火墙：确保端口开放且可访问

工具未出现 ​

症状：连接器可连接，但看不到任何工具。

解决方案：

  1. 检查服务器配置：验证 MCP 服务器配置是否正确

    bash
    npx -y @1mcp/agent mcp list

  2. 重启双方：同时重启 1MCP 和 Claude Desktop

身份验证问题 ​

症状：OAuth 身份验证失败或重复要求凭据。

解决方案：

  1. 检查 OAuth 配置：确认在 1MCP 中已启用 OAuth
  2. 发行者匹配：将 --external-url 设为你的公共 HTTPS 源（无路径），并与 Claude 的连接器 URL 源完全一致
  3. 验证凭据：在 Claude Desktop 中确认 Client ID/Secret
  4. 清除缓存：移除并重新添加连接器

调试步骤 ​

  1. 测试直连：

    bash
    # 测试暴露的 HTTPS 端点
curl -X POST https://your-domain.com/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0","id": 1,"method": "initialize","params": {"protocolVersion": "2025-06-18","capabilities": {},"clientInfo": {"name": "ExampleClient","title": "Example Client Display Name","version": "1.0.0"}}}'

  2. 查看服务器日志：

    bash
    ONE_MCP_LOG_LEVEL=debug npx -y @1mcp/agent serve --transport http --port 3001

  3. 健康检查：

    bash
    curl https://your-domain.com/health

安全注意事项 ​

生产部署 ​

  1. 通过反向代理提供 HTTPS（nginx/Caddy/Traefik）
  2. 生产环境启用 OAuth：--enable-auth
  3. 网络加固：防火墙、VPN/私网、在代理侧限速；被代理时绑定到 localhost

信任与权限 ​

  • 谨慎连接：仅连接受信任的 1MCP 服务器
  • 理解权限：明确哪些工具会被暴露
  • 定期审计：周期性检查已连接的连接器及其权限

高级用法 ​

多个环境 ​

你可以为不同环境添加多个 1MCP 连接器：

  1. 开发环境：

    • 名称：“1MCP Dev”
    • URL：https://dev-abc123.ngrok-free.app/mcp（使用 ngrok）

  2. 生产环境：

    • 名称：“1MCP Prod”
    • URL：https://prod-server.com/mcp
    • 配置生产 OAuth 凭据

服务器筛选 ​

bash
# 仅暴露特定能力
npx -y @1mcp/agent serve --transport http --port 3001 --filter "context7,sequential"

最佳实践 ​

本地 ​

  • 先启动 HTTP 服务器 → serve（使用默认端口 3050）
  • 创建用于服务器筛选的预设 → preset create
  • 在代理命令中使用 --preset 参数进行筛选
  • 预览整合 → --dry-run
  • 自动备份；整合后重启 Claude Desktop
  • 保持 agent 更新；用 mcp status 监控

远程 ​

  • 先从简单开始（无鉴权），再为生产增加 OAuth + HTTPS
  • 健康检查与监控
  • 定期复查权限；保持服务器更新

示例 ​

本地（推荐） ​

bash
# 1. 安装 1MCP 代理
npm install -g @1mcp/agent

# 2. 添加一些常用 MCP 服务器（带标签用于筛选）
npx -y @1mcp/agent mcp add context7 --tags=documentation,docs -- npx -y @upstash/context7-mcp
npx -y @1mcp/agent mcp add sequential --tags=thinking,analysis -- npx -y @modelcontextprotocol/server-sequential-thinking
npx -y @1mcp/agent mcp add playwright --tags=browser,testing -- npx -y @playwright/mcp

# 3. 为 Claude Desktop 创建预设
npx -y @1mcp/agent preset create claude-desktop --filter "documentation OR thinking OR browser"

# 4. 启动 1MCP HTTP 服务器
npx -y @1mcp/agent serve

# 5. 在另一个终端中预览整合
npx -y @1mcp/agent app consolidate claude-desktop --dry-run

# 6. 执行整合
npx -y @1mcp/agent app consolidate claude-desktop

# 7. 重启 Claude Desktop

# 8. 验证工具可用
npx -y @1mcp/agent mcp status

整合后，Claude Desktop 将自动使用如下配置：

json
{
  "mcpServers": {
    "1mcp": {
      "command": "npx",
      "args": ["-y", "@1mcp/agent", "proxy", "--preset", "claude-desktop"]
    }
  }
}

使用自定义预设 ​

您可以在配置 Claude Desktop 时指定任何预设：

json
{
  "mcpServers": {
    "1mcp": {
      "command": "npx",
      "args": ["-y", "@1mcp/agent", "proxy", "--preset", "my-custom-preset"]
    }
  }
}

为不同用例创建不同的预设：

bash
# 开发预设
npx -y @1mcp/agent preset create dev --filter "filesystem OR git OR testing"

# 文档预设
npx -y @1mcp/agent preset create docs --filter "documentation OR writing"

# 分析预设
npx -y @1mcp/agent preset create analysis --filter "data OR thinking"

远程 + ngrok ​

适用于需要远程访问的开发场景：

bash
# 1. 安装与配置 1MCP
npm install -g @1mcp/agent
npx -y @1mcp/agent mcp add context7 -- npx -y @upstash/context7-mcp
npx -y @1mcp/agent mcp add sequential -- npx -y @modelcontextprotocol/server-sequential-thinking

# 2. 通过 ngrok 暴露
ngrok http 3001

# 3. 启动服务器，使用 ngrok 提供的 URL
npx -y @1mcp/agent serve --transport http --port 3001 --external-url https://abc123.ngrok-free.app

# 4. 在 Claude Desktop 中添加连接器：
#    - Name: "My 1MCP Server"
#    - URL:  "https://abc123.ngrok-free.app/mcp"

# 5. 验证工具可用

生产 + Nginx ​

bash
# 1. 启动 1MCP 服务器（为安全起见建议绑定到 localhost）
npx -y @1mcp/agent serve --transport http --port 3001 --enable-auth --external-url https://your-domain.com

# 2. 配置 nginx 将 HTTPS 代理到本地 HTTP
# 3. 在 Claude Desktop 中添加连接器：
#    - Name: "Production 1MCP"
#    - URL:  "https://your-domain.com/mcp"
#    - 配置 OAuth 凭据

# 4. 验证工具可用

获取帮助 ​

遇到问题可参考：

  1. 查看上文的故障排除
  2. 针对本地整合问题：
    • 试试 npx -y @1mcp/agent app consolidate claude-desktop --force
    • 使用 npx -y @1mcp/agent mcp status 查看服务器健康
    • 使用 npx -y @1mcp/agent app restore claude-desktop 回滚
  3. 针对远程连接器问题：
  4. 在我们的 GitHub 仓库 提交 Issue
  5. 查阅 1MCP 文档 了解服务器配置

我应该使用哪种方法？ ​

选择本地配置整合如果： ​

  • ✅ 你想要基于预设的服务器筛选
  • ✅ 你在本机使用 Claude Desktop
  • ✅ 你不需要远程访问
  • ✅ 你想要集中式服务器管理
  • ✅ 你更喜欢使用代理桥接 HTTP 服务器到 Claude Desktop

选择远程自定义连接器如果： ​

  • ✅ 你拥有 Claude Pro/Max/Team/Enterprise 计划
  • ✅ 你需要访问集中式 1MCP 服务器
  • ✅ 你熟悉网络/HTTPS 配置
  • ✅ 你希望在多个客户端之间共享 MCP 服务器
  • ✅ 你需要 OAuth 身份验证

后续步骤 ​

基于 Apache 2.0 许可发布

版权所有 © 2025-present 1MCP