MCP服务器

此仓库包含了各种模型上下文协议（MCP）服务器的配置和设置，用于与Claude桌面和其他AI助手一起使用。

简介

该项目旨在简化MCP服务器的设置和管理，以便与Claude产品一起使用。我主要在Mac OS X上使用这些设置与Claude桌面和Claude Code一起工作，并计划在未来将其集成到Cursor中。

如果你使用的是Windows系统，可以将此作为一般指南，但需要相应地调整路径和命令。

该配置是在Cursor代理视图和网络搜索的帮助下，在Claude的帮助下制定的，以确保遵循最佳实践。它设计为安全、灵活且易于维护。

MCP组织最佳实践

目录结构

我们遵循以下约定来组织与MCP相关的文件：

~/mcp/                         # 主MCP项目目录
├── .venv/                     # 项目特定MCP服务器的Python虚拟环境
├── claude_desktop_config.json # 参考配置文件
├── README.md                  # 此文档
├── install-config.sh          # 安装脚本
├── setup-mcp-secrets.sh       # 密钥设置脚本
└── uv_notes.md                # 关于使用uv进行Python依赖项管理的笔记

虚拟环境管理

对于基于Python的MCP服务器，我们遵循以下约定：

1. 项目特定的MCP服务器：

   • 在项目目录中创建一个项目本地虚拟环境
   • 使用uv在此环境中安装MCP服务器
   • 示例：cd ~/mcp && uv venv && source .venv/bin/activate

2. 全局MCP服务器：

   • 使用uv tool install <server-name>安装
   • 这些可以在~/.local/bin/找到

依赖项管理

始终使用uv进行Python包管理：

• 工具安装：uv tool install <tool-name>
• 虚拟环境创建：uv venv
• 包安装：uv pip install <package-name>

已安装的MCP服务器

已安装并配置了以下MCP服务器：

1. 文件系统 - 访问本地文件系统中的文件和目录

   • 通过：npm install -g @modelcontextprotocol/server-filesystem安装
   • 配置访问所需目录的路径

2. SQLite - 查询SQLite数据库

   • 通过：uv tool install mcp-server-sqlite安装
   • 配置数据库文件的路径

   SQLite数据库注册表：

   要添加多个项目数据库，请更新claude_desktop_config.json中的SQLite配置：

   "sqlite": {
     "command": "path/to/mcp-server-sqlite",
     "args": [
       "--db-path",
       "path/to/your/database.db"
     ],
     "env": {
       "MCP_SQLITE_REGISTRY": "path/to/db1.sqlite:path/to/db2.db:path/to/db3.sqlite"
     }
   }
   

   然后在Claude中通过指定完整路径来访问这些数据库：

   -- 查询第一个数据库
   SELECT * FROM users WHERE id = 1 -- 使用path/to/db1.sqlite
   
   -- 切换到第二个数据库
   USE DATABASE path/to/db2.db;
   SELECT * FROM products;
   

   重要提示： 修改配置文件后，务必重启Claude桌面。

3. Puppeteer - 网页浏览和自动化

   • 通过：npm install -g @modelcontextprotocol/server-puppeteer安装
   • 配置为使用本地Chrome安装
   • 环境变量：
     • PUPPETEER_HEADLESS：设置为“true”以启用无头模式
     • PUPPETEER_EXECUTABLE_PATH：指向本地Chrome安装
   • 注意：我们使用Node.js实现以获得更好的本地网络访问且无需Docker依赖

4. GitHub - 访问GitHub存储库和问题

   • 通过：npm install -g @modelcontextprotocol/server-github安装
   • 需要环境变量：GITHUB_PERSONAL_ACCESS_TOKEN

5. 时间 - 获取当前时间和日期信息

   • 通过：uv tool install mcp-server-time安装
   • 配置本地时区

6. 获取 - 发送HTTP请求并解析网页内容

   • 通过：uv tool install mcp-server-fetch安装
   • 增强了双配置以更好地处理HTTP请求
   • 添加环境变量以引导Claude优先选择获取方式

7. CLI - 安全执行命令

   • 在项目虚拟环境中安装：cd ~/mcp && source .venv/bin/activate && uv pip install cli-mcp-server
   • 配置为具有适当权限的HTTP操作

配置

Claude桌面配置文件位于：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：C:\Users\USERNAME\AppData\Roaming\Claude\claude_desktop_config.json

设置你的配置

此仓库包括两个配置文件：

• claude_desktop_config.template.json - 包含路径和设置占位符的模板
• 你的实际配置文件（默认情况下不包含在git中）

设置你的配置：

1. 创建自定义配置文件：

cp claude_desktop_config.template.json claude_desktop_config.custom.json

2. 编辑你的自定义配置文件，包含具体的路径和设置：

# 使用你喜欢的文本编辑器编辑
nano claude_desktop_config.custom.json

3. 安装你的配置：

# 在macOS上
./install-config.sh

# 在Windows（PowerShell）上
# 安装脚本将使用你的自定义配置

重要提示： 更新配置文件后，必须重启Claude桌面才能使更改生效。

HTTP请求处理

我们已经实施了一个强大的策略来处理HTTP请求，使用多个MCP服务器：

1. 主获取服务器

   • 命令：mcp-server-fetch
   • 增强了自定义用户代理
   • 环境变量以信号Claude优先选择此方法

2. HTTP别名服务器

   • 同一获取服务器，但有不同的名称和配置
   • 使得Claude更容易识别何时应发出HTTP请求

3. CLI服务器备用

   • 处理curl、wget和http命令
   • 配置了常见HTTP操作的适当标志
   • 在项目特定的虚拟环境中运行

这种分层方法确保Claude有多种方式来发送HTTP请求，并内置了回退机制和明确的首选方法信号。

安全管理密钥

几个MCP服务器需要API密钥、令牌或其他敏感信息。以下是完整的设置过程，以确保你的密钥正确工作：

第一步：创建环境变量文件

创建专用环境文件（推荐的方法）：

# 创建环境变量文件
touch ~/.claude_env
chmod 600 ~/.claude_env  # 限制权限以保证安全

将你的密钥添加到此文件中（每行一个）：

CLAUDE_DESKTOP_GITHUB_TOKEN=your_github_token_here
BRAVE_API_KEY=your_brave_api_key_here
# 根据需要添加其他密钥

第二步：确保变量加载

向你的shell配置文件添加代码，以便在shell启动时自动加载这些变量：

# 打开你的shell配置文件
echo 'if [ -f ~/.claude_env ]; then
  export $(grep -v "^#" ~/.claude_env | xargs)
fi' >> ~/.zshrc  # 或者对于bash用户，使用~/.bashrc

然后重新加载你的配置文件：

source ~/.zshrc  # 或者source ~/.bashrc

第三步：验证环境变量

验证变量是否正确加载：

# 应该显示你的token的前几个字符
echo ${CLAUDE_DESKTOP_GITHUB_TOKEN:0:5}...

第四步：测试API访问（可选但推荐）

对于GitHub，测试你的token是否有效：

curl -s -H "Authorization: token $CLAUDE_DESKTOP_GITHUB_TOKEN" https://api.github.com/user | grep login

第五步：在配置中引用

你的claude_desktop_config.json应该引用这些变量：

"github": {
  "command": "path/to/node",
  "args": [
    "path/to/server-github/dist/index.js"
  ],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "${CLAUDE_DESKTOP_GITHUB_TOKEN}"
  }
}

第六步：重启Claude桌面

完全退出并重新启动Claude桌面以获取新的环境变量。

自动化设置脚本

此仓库包含setup-mcp-secrets.sh，它自动化了上述步骤。

故障排除

常见问题

1. “身份验证失败：凭据无效”错误

   • 问题：环境变量已定义但未加载到Claude桌面的环境中
   • 解决方案：确保你的shell配置文件加载了变量并重启Claude桌面
   • 验证：在终端中运行echo $CLAUDE_DESKTOP_GITHUB_TOKEN检查变量是否设置

2. 环境变量无法持久

   • 问题：变量被临时设置但在会话之间没有持久保存
   • 解决方案：确保加载代码在你的shell配置文件中且文件路径正确
   • 修复：检查变量名和文件路径中的拼写错误

3. API访问在终端中有效但在Claude桌面中无效

   • 问题：GUI应用程序有时不会继承所有环境变量
   • 解决方案：注销并重新登录，或重启计算机
   • 替代方案：尝试从终端启动Claude桌面：open -a "Claude"

4. “目标已关闭”错误与Puppeteer

   • 问题：Apple Silicon Mac上的架构不匹配
   • 解决方案：确保你使用了与架构兼容的Puppeteer配置

5. “收到请求之前初始化未完成”错误与SQLite

   • 问题：SQLite MCP服务器未正确启动
   • 解决方案：
     1. 使用uv安装：uv tool install mcp-server-sqlite
     2. 更新配置以使用全局路径
     3. 完全重启Claude桌面

6. MCP更改未生效

   • 问题：Claude桌面缓存了配置
   • 解决方案：在更改配置后总是完全重启Claude桌面

7. Claude试图使用curl而不是获取服务器

   • 问题：Claude未能正确识别用于HTTP请求的获取服务器
   • 解决方案：
     1. 添加环境变量以表示偏好（MCP_FETCH_PREFERRED: "true"）
     2. 如我们的配置所示创建HTTP别名服务器
     3. 添加CLI服务器作为curl命令的备用

8. 获取MCP服务器的JSON解析错误

   • 问题：在获取网页内容时出现“意外结束JSON输入”或“意外标记”等错误
   • 症状：当Claude尝试搜索或从网站获取内容时出现多个错误消息
   • 解决方案：
     1. 配置获取服务器以使用回退解析：MCP_FETCH_PARSE_FALLBACK: "text"
     2. 添加--ignore-robots-txt到参数以避免解析robots.txt文件的问题
     3. 设置适当的超时和最大大小限制
     4. 在做出这些更改后完全重启Claude桌面

   示例配置以增强获取服务器：

   "fetch": {
     "command": "path/to/mcp-server-fetch",
     "args": [
       "--user-agent", "Claude Desktop MCP Client",
       "--ignore-robots-txt"
     ],
     "env": {
       "MCP_FETCH_PREFERRED": "true",
       "MCP_FETCH_DEFAULT": "true",
       "MCP_FETCH_PARSE_FALLBACK": "text",
       "MCP_FETCH_MAX_SIZE": "5242880",
       "MCP_FETCH_TIMEOUT": "60000"
     }
   }
   

将Claude桌面MCP添加到浏览器中的Claude

要在Claude Web或Claude Code中使用Claude桌面MCP服务器，你可以运行：

# 在macOS上
osascript -e 'tell application "Claude" to activate' && sleep 2 && osascript -e 'tell application "System Events" to keystroke "m" using {command down, shift down}'

# 在Windows（PowerShell）上
Start-Process "Claude" && Start-Sleep -Seconds 2 && Add-Type -AssemblyName System.Windows.Forms && [System.Windows.Forms.SendKeys]::SendWait("^+m")

这将激活Claude桌面并触发键盘快捷键以将MCP服务器添加到当前浏览器会话中。

使用uv

有关使用uv进行基于Python的MCP服务器的详细信息，请参阅uv_notes.md。

参考资料

• MCP服务器GitHub仓库
• MCP安装程序
• CLI MCP服务器
• 构建MCP服务器指南

安全最佳实践

在处理需要API密钥和令牌的MCP服务器时，遵循安全最佳实践非常重要：

1. 永远不要提交敏感信息：

   • API密钥、令牌和凭证不应提交到你的仓库
   • 使用环境变量和单独的文件，这些文件在.gitignore中被排除

2. 避免意外提交：

   • 使用特定的git add命令而不是通用的git add .
   • 提交前使用git diff --cached审查更改
   • 设置预提交钩子以检查敏感数据

3. 如果敏感数据意外提交：

   • 使用git filter-repo永久从历史记录中删除
   • 立即更改任何暴露的凭证
   • 强制推送清理后的仓库

4. 配置分离：

   • 使用带有敏感值占位符的模板文件
   • 保持实际配置文件本地且不包含在git中
   • 我们将claude_desktop_config.template.json与实际配置分离的方法提供了这种保护

有关从仓库中移除敏感数据的更多细节，请参阅GitHub的官方文档。