MCP 服务器

此仓库包含各种模型上下文协议 (MCP) 服务器的配置和设置，用于 Claude Desktop 和其他 AI 助手。

简介

此项目的创建旨在简化 MCP 服务器的设置和管理，以便与 Claude 产品一起使用。我主要在 Mac OS X 上将此设置与 Claude Desktop 和 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 <服务器名称> 安装
   • 这些服务器位于 ~/.local/bin/

依赖管理

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

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

已安装的 MCP 服务器

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

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

   • 通过以下方式安装：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 Desktop。

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. Time - 获取当前时间和日期信息

   • 通过以下方式安装：uv tool install mcp-server-time
   • 使用您的本地时区进行配置

6. Fetch - 发出 HTTP 请求并解析 Web 内容

   • 通过以下方式安装：uv tool install mcp-server-fetch
   • 通过双重配置增强，以获得更好的 HTTP 请求处理
   • 添加了环境变量以提示 Claude 优先使用 fetch 进行 HTTP 请求

7. CLI - 安全地执行命令

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

配置

Claude Desktop 配置文件位于：

• 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 Desktop 才能使更改生效。

HTTP 请求处理

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

1. 主 Fetch 服务器

   • 命令：mcp-server-fetch
   • 使用自定义用户代理增强
   • 环境变量，用于指示 Claude 优先使用此方法

2. HTTP 别名服务器

   • 具有不同名称和配置的相同 fetch 服务器
   • 使 Claude 更容易识别何时应发出 HTTP 请求

3. CLI 服务器回退

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

这种分层方法确保 Claude 有多种发出 HTTP 请求的方式，具有内置的回退和关于应优先使用哪种方法的明确信号。

安全地管理密钥

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

步骤 1：创建环境变量文件

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

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

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

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

步骤 2：确保变量已加载

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

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

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

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

步骤 3：验证环境变量

验证变量是否已正确加载：

# 应显示您的令牌的前几个字符
echo ${CLAUDE_DESKTOP_GITHUB_TOKEN:0:5}...

步骤 4：测试 API 访问（可选但推荐）

对于 GitHub，测试您的令牌是否有效：

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

步骤 5：在配置中引用

您的 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}"
  }
}

步骤 6：重启 Claude Desktop

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

自动化设置脚本

此仓库包含 setup-mcp-secrets.sh，它可以自动执行上述步骤。

故障排除

常见问题

1. "Authentication Failed: Bad credentials" 错误

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

2. 环境变量未持久化

   • 问题： 变量是临时设置的，但不会跨会话持久化
   • 解决方案： 确保加载代码位于您的 shell 配置文件中，并且文件路径正确
   • 修复： 检查变量名称和文件路径中是否存在拼写错误

3. API 访问在终端中有效，但在 Claude Desktop 中无效

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

4. Puppeteer 出现 "Target closed" 错误

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

5. SQLite 出现 "Received request before initialization was complete" 错误

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

6. MCP 更改未生效

   • 问题： Claude Desktop 缓存配置
   • 解决方案： 在配置更改后，始终完全重启 Claude Desktop

7. Claude 尝试使用 curl 而不是 fetch 服务器

   • 问题： Claude 未正确识别用于 HTTP 请求的 fetch 服务器
   • 解决方案：
     1. 添加环境变量以指示首选项 (MCP_FETCH_PREFERRED: "true")
     2. 创建一个 HTTP 别名服务器，如我们的配置中所示
     3. 添加 CLI 服务器作为 curl 命令的回退

8. fetch MCP 服务器出现 JSON 解析错误

   • 问题： 从网站获取 Web 内容时，出现 "Unexpected end of JSON input" 或 "Unexpected token" 等错误
   • 症状： 当 Claude 尝试搜索或从网站获取内容时，出现多个错误消息
   • 解决方案：
     1. 使用回退解析配置 fetch 服务器：MCP_FETCH_PARSE_FALLBACK: "text"
     2. 将 --ignore-robots-txt 添加到 args 以避免 robots.txt 文件出现解析问题
     3. 设置适当的超时和最大大小限制
     4. 在进行这些更改后，完全重启 Claude Desktop

   用于稳健的 fetch 服务器的示例配置：

   "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 Desktop MCP 添加到 Web 浏览器中的 Claude

要从 Claude Desktop 在 Claude web 或 Claude Code 中使用您的 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 Desktop 并触发键盘快捷键，以将 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 的官方文档。