claude-desktop.md•17.8 kB
# 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`(健康检查)。
2. 通过 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)
3. 在 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**”
- 你会看到类似如下的对话框:

3. **输入连接详情**
- **Name**:为连接器输入名称(例如“1mcp”)
- **URL**:输入公共 HTTPS URL:
- 使用 ngrok:`https://abc123.ngrok-free.app/mcp`
- 使用反向代理:`https://your-domain.com/mcp`
- **OAuth Client ID**(可选):若启用身份验证
- **OAuth Client Secret**(可选):若启用身份验证
4. **确认信任**
- 阅读安全警告
- 点击“**Add**”确认信任该连接器
### 步骤 3:验证连接
添加连接器后,你应能看到 1MCP 提供的工具:

实际显示的工具取决于你的 1MCP 实例中已配置的 MCP 服务器,常见包括:
- Context7 文档工具
- 顺序思维工具
- Playwright 浏览器自动化
- 以及你添加的其他 MCP 服务器
### 步骤 4:开始使用工具
连接后,1MCP 工具会出现在 Claude Desktop 的聊天界面中:

你现在可以在与 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 --tags "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 --tags "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. 针对**远程连接器问题**:
- 参考 Anthropic 文档:
- [通过远程 MCP 服务器构建自定义连接器](https://support.anthropic.com/en/articles/11503834-building-custom-connectors-via-remote-mcp-servers)
- [浏览并从目录连接到工具](https://support.anthropic.com/en/articles/11724452-browsing-and-connecting-to-tools-from-the-directory)
4. 在我们的 [GitHub 仓库](https://github.com/1mcp-app/agent) 提交 Issue
5. 查阅 [1MCP 文档](/guide/getting-started) 了解服务器配置
## 我应该使用哪种方法?
### 选择**本地配置整合**如果:
- ✅ 你想要基于预设的服务器筛选
- ✅ 你在本机使用 Claude Desktop
- ✅ 你不需要远程访问
- ✅ 你想要集中式服务器管理
- ✅ 你更喜欢使用代理桥接 HTTP 服务器到 Claude Desktop
### 选择**远程自定义连接器**如果:
- ✅ 你拥有 Claude Pro/Max/Team/Enterprise 计划
- ✅ 你需要访问集中式 1MCP 服务器
- ✅ 你熟悉网络/HTTPS 配置
- ✅ 你希望在多个客户端之间共享 MCP 服务器
- ✅ 你需要 OAuth 身份验证
## 后续步骤
- 了解[代理命令](/commands/proxy)的详细配置选项
- 探索[服务器筛选选项](/guide/advanced/server-filtering)中的预设和标签
- 为你的 MCP 服务器设置[服务器管理](/guide/essentials/server-management)
- 配置[应用整合](./app-consolidation)以便无缝管理其他应用
- 了解[身份验证配置](/guide/advanced/authentication)用于远程设置