Awesome MCP Servers 实战：搭一个万能 AI 工具库

你有没有遇到过这种情况：跟 AI 聊天时，它突然说“我无法访问你的文件”或者“我没有权限查询数据库”？那一刻你才意识到，原来 AI 助手的能力是被“关在笼子里”的——它只能靠训练数据里的知识回答问题，没法碰你电脑上的任何东西。

MCP（Model Context Protocol）就是来打破这个笼子的。你可以把它想象成一个万能转接头：AI 模型通过这个协议，能安全地连接到你本地的文件、数据库、甚至各种在线服务。而 Awesome MCP Servers 这个项目，就是一个精心整理的工具目录——里面收录了上百个现成的 MCP 服务器，覆盖从文件系统、数据库到 GitHub API、天气查询、邮件发送等等场景。

换句话说，这一章要解决的核心问题是：让你明白 MCP 是什么、为什么你需要它，以及 Awesome MCP Servers 这个项目能帮你省多少事。

---

先搞清楚：MCP 到底在解决什么问题？

假设你正在用 Claude 写一份周报，需要查一下上个月的销售数据。没有 MCP 的情况下，你得手动打开数据库客户端、跑 SQL、复制结果、再粘贴给 AI。有了 MCP，你只需要说一句“帮我查一下上个月销售额”，AI 就能直接通过 MCP 服务器连接数据库，把结果拿回来。

MCP 本质上是一套标准化的通信协议，定义了 AI 模型和外部工具之间怎么“握手”、怎么“传数据”。它有点像 USB-C 接口——不管背后是什么设备，只要插口统一，就能互通。MCP 服务器就是那个“设备端”，负责把各种能力（读文件、查数据库、调 API）包装成 AI 能理解的接口。

Awesome MCP Servers 是什么？为什么它值得你花时间？

这个项目（punkpeye/awesome-mcp-servers）是一个社区维护的精选列表，收录了各种 MCP 服务器的实现。它最大的价值在于：你不用从零开始写代码。想给 AI 加上文件操作能力？列表里已经有现成的。想让它能查 GitHub 仓库？也有。想让它能控制浏览器？也有。

项目主页上有个醒目的提示：它还有一个网页版目录，和 GitHub 仓库同步更新。这意味着你可以直接在线浏览、搜索，不用在终端里翻 README。

这个目录怎么组织的？看懂标签就不迷路

打开项目，你会看到一堆 emoji 标签。别被它们吓到，其实逻辑很简单：

• 语言标签：🐍 表示 Python，📇 表示 TypeScript/JavaScript，🏎️ 是 Go，🦀 是 Rust，等等。这告诉你这个服务器用什么语言写的——如果你需要自己改代码，选你熟悉的语言就行。
• 范围标签：☁️ 表示云端服务（比如调用天气 API），🏠 表示本地服务（比如操作你电脑上的文件）。一个简单的判断标准：如果 MCP 服务器跟本地安装的软件交互（比如控制 Chrome 浏览器），就是本地；如果它调用远程 API，就是云端。
• 操作系统标签：🍎 是 macOS，🪟 是 Windows，🐧 是 Linux。有些服务器只支持特定系统，安装前看一眼能省不少麻烦。

另外，带 🎖️ 标记的是官方实现，意味着更稳定、文档更全。

服务器分类：从文件系统到社交媒体，应有尽有

项目把服务器分成了几十个类别，每个类别都有对应的 emoji 图标。比如：

• 📂 文件系统：让 AI 能读写你电脑上的文件
• 🗄️ 数据库：连接 SQLite、PostgreSQL 等数据库
• ☁️ 云平台：对接 AWS、GCP 等云服务
• 💬 通信：集成 Slack、Discord 等聊天工具
• 🔄 版本控制：操作 GitHub、GitLab 仓库

每个类别下都有多个具体实现。比如“文件系统”类别里，可能有专门操作本地文件的服务器，也有能访问云存储的。你不需要全记住，用到的时候来翻就行。

一个真实的场景：从零到能查数据库

假设你想让 AI 助手能查询本地的 SQLite 数据库。按照传统方式，你得自己写一个 MCP 服务器，定义接口、处理请求、返回结果——至少半天功夫。但有了 Awesome MCP Servers，你只需要：

1. 在项目列表的“Databases”分类下找到 SQLite 相关的服务器
2. 查看它的 README，通常会有几行安装命令
3. 运行 npx 或 pip install 启动它
4. 在 AI 客户端（比如 Claude Desktop）里配置一下连接

整个过程可能不到 10 分钟。这就是这个项目的核心价值：把“造轮子”的时间省下来，直接用在真正需要解决的问题上。

接下来你会学到什么

这一章只是开胃菜。后面的章节会手把手带你：

• 用 5 分钟跑通第一个 MCP 服务器（查天气）
• 从目录里挑出你需要的服务器
• 安装配置本地和云端服务器
• 让 AI 同时使用多个工具
• 解决各种启动错误

你现在已经知道了 MCP 是什么、Awesome MCP Servers 能帮你做什么。下一步，我们直接动手——第二章就会让你在 Claude 里查天气，感受一下 MCP 的魔力。

想快速体验 MCP 到底有多神奇？最好的办法就是亲手跑一个能用的例子。这一章我们就用「查天气」这个最经典的需求，5 分钟内让 Claude 变成一个能实时查天气的助手。

你不需要懂任何后端知识，甚至不用装 Node.js——我们直接用 npx 一键启动，连安装步骤都省了。

前置条件

• 你已经装好了 Claude Desktop（或者任何支持 MCP 的客户端，比如 VS Code 的 Copilot Chat）
• 电脑上装了 Node.js（版本 18 以上就行，没装的话去 nodejs.org 下载 LTS 版）
• 网络能访问 npm 仓库（国内用户可能需要科学上网，或者配置 npm 镜像）

第一步：找到天气服务器

打开 Awesome MCP Servers 的网页目录，在搜索框里输入 weather。你会看到好几个结果，我们选最常用的那个——@nicholasgriffintn/mcp-server-weather。

这个服务器用的是美国国家气象局（NWS）的公开 API，完全免费，不需要注册 API Key。它支持查当前天气、未来预报、还有恶劣天气警报。

第二步：配置 Claude Desktop

打开 Claude Desktop，点击左上角的菜单 → Settings → Developer → Edit Config。这会打开一个叫 claude_desktop_config.json 的文件。

把下面这段配置粘贴进去：

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": [
        "-y",
        "@nicholasgriffintn/mcp-server-weather"
      ]
    }
  }
}

保存文件，然后完全退出 Claude Desktop（不是最小化，是右键退出）。重新打开它。

第三步：测试连接

打开一个新的对话，输入：

今天纽约的天气怎么样？

Claude 会先思考一下，然后调用天气服务器，返回类似这样的结果：

纽约今天（2025年1月15日）的天气情况如下：

• 温度：当前 2°C，体感温度 -3°C
• 天气：多云，有轻微降雪可能
• 风速：西北风 15-25 km/h
• 湿度：65%
• 日出/日落：07:15 / 16:45

如果看到这个，恭喜你——第一个 MCP 服务器已经跑通了！

常见问题排查

Q: Claude 说“没有找到天气工具”或者报错。 A: 检查 claude_desktop_config.json 的格式。JSON 里不能有多余的逗号，键名必须用双引号。最稳妥的办法：用 JSON 验证工具 检查一下。

Q: 启动后 Claude 没反应，或者一直转圈。 A: 可能是网络问题。npx 需要下载包，如果网络慢可以等一会儿。如果超时，试试在终端里先手动跑一次 npx -y @nicholasgriffintn/mcp-server-weather，等它下载完再重启 Claude。

Q: 查中国城市天气报错。 A: 这个服务器用的是美国气象局的数据，只支持美国本土。想查中国天气，需要换一个支持 OpenWeatherMap 或和风天气的服务器。我们后面会讲到怎么换。

小技巧：让查询更精准

Claude 有时候会猜城市名，比如你说“查天气”，它可能默认查旧金山。最好明确指定城市和州（美国城市），或者直接说经纬度：

查一下 40.7128°N, 74.0060°W 的天气

这样 Claude 会直接调用坐标参数，结果更准确。

下一步

你已经跑通了第一个 MCP 服务器。接下来，我们会在第 3 章教你怎么从 Awesome MCP Servers 的目录里快速找到你需要的服务器——不管是查数据库、发邮件还是操作文件，都有现成的工具等着你。

逛超市最怕什么？不是价格贵，是货架太多、标签太乱，你明明只想买瓶酱油，结果在调味区转了半小时。Awesome MCP Servers 的目录现在就面临这个问题——它已经收录了上百个服务器，分成了四十多个分类，每个分类下还有一堆项目。如果你直接打开那个 README，大概率会像站在超市入口一样茫然：我从哪开始看？

这一章就是帮你解决这个问题的。我们不急着安装任何东西，先学会怎么快速读懂这个目录的结构，然后根据你自己的需求，精准定位到最合适的服务器。等你读完这章，再打开那个 README，就不会觉得它是一堵墙，而是一张清晰的地图。

前置条件

• 你已经打开过 Awesome MCP Servers 的 GitHub 页面（上一章我们用它查过天气）
• 你大概知道 MCP 服务器是干什么的（让 AI 能调用外部工具）

第一步：先看目录顶部的“分类索引”

打开 README，往下翻一点，你会看到一大串带 emoji 的标题，比如 🔗 - Aggregators、🎨 - Art & Culture、📂 - Browser Automation……一直到 🏢 - Workplace & Productivity。这四十多个分类就是整个超市的货架分区。

每个分类前面都有一个 emoji 图标，这不是随便选的。比如：

• 🗄️ 是数据库（Databases）
• 📂 是文件系统（File Systems）
• ☁️ 是云平台（Cloud Platforms）
• 🔄 是版本控制（Version Control）

这些 emoji 的作用是让你扫一眼就能大概知道这个分类是干什么的，不用逐字读英文标题。如果你要找“能操作 GitHub 的服务器”，看到 🔄 - Version Control 基本就猜对了。

实用技巧：如果你在找某个特定功能，可以先在页面里按 Ctrl+F（Mac 是 Cmd+F），搜那个功能的关键词，比如“GitHub”“SQLite”“Slack”。这样能直接跳到对应的分类，不用手动翻。

第二步：理解每个服务器条目上的“标签”

点进任何一个分类，你会看到类似这样的条目：

- [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) 📇 ☁️ 🍎 🪟 🐧 - 一个统一的 MCP 服务器，聚合多个服务。

重点看那些 emoji 标签，它们告诉你三个关键信息：

1. 编程语言：服务器是用什么写的。最常见的是 📇（TypeScript/JavaScript）和 🐍（Python）。如果你电脑上已经装了 Node.js，选 📇 的服务器通常更省事，因为很多可以直接用 npx 启动（下一章会讲）。如果你更熟悉 Python，就找 🐍 的。

2. 作用范围：这个服务器是跟本地软件打交道（🏠），还是调用远程 API（☁️）。比如上一章我们用的天气服务器就是 ☁️，因为它去调了天气网站的 API。而一个能控制你电脑上 Chrome 浏览器的服务器就是 🏠。这个区分很重要：☁️ 的服务器通常需要网络和 API 密钥，🏠 的服务器可能需要在本地安装对应的软件。

3. 操作系统：🍎（macOS）、🪟（Windows）、🐧（Linux）。大部分服务器是跨平台的，三个图标都有。但如果只看到一个 🍎，说明它只支持 macOS，你在 Windows 上跑可能会报错。

常见误区：别把 🏠（本地）和 🐍（Python）搞混。🏠 说的是服务器跟谁通信，🐍 说的是代码用什么写的。一个 Python 写的服务器也可以调用远程 API，那就是 🐍 ☁️。

第三步：用“官方标识”筛选靠谱的服务器

在 README 的图例（Legend）部分，有一个 🎖️ 图标，意思是“官方实现”。如果你看到一个服务器前面有 🎖️，说明它是那个服务（比如 GitHub、Slack、Cloudflare）官方出的 MCP 服务器，不是第三方爱好者写的。

为什么这很重要？ 官方服务器通常文档更全、更新更及时、bug 更少。如果你在找某个知名服务的 MCP 集成，优先看有没有 🎖️ 标记的。比如 GitHub 的官方 MCP 服务器就在 🔄 - Version Control 分类里，带 🎖️ 标记。

第四步：根据你的场景快速定位

现在我们来模拟几个真实场景，看看怎么用上面的方法快速找到目标。

场景一：你想让 AI 能直接读写你电脑上的文件

• 目标分类：📂 - File Systems
• 筛选条件：🏠（本地服务），因为文件在你电脑上
• 操作系统：看你用什么系统，选对应的图标
• 结果：你会看到几个文件系统服务器，比如 modelcontextprotocol/filesystem（这是官方实现，带 🎖️ 标记）

场景二：你想让 AI 能查询公司的 PostgreSQL 数据库

• 目标分类：🗄️ - Databases
• 筛选条件：🏠（本地服务，因为数据库可能在你内网），或者 ☁️（如果数据库在云端）
• 语言偏好：如果你团队用 Python，找 🐍 的；如果用 Node.js，找 📇 的
• 结果：你会看到多个数据库服务器，包括 PostgreSQL、MySQL、SQLite 等。选那个带 🎖️ 的官方实现最稳妥

场景三：你想让 AI 能发 Slack 消息

• 目标分类：💬 - Communication
• 筛选条件：☁️（远程 API），因为 Slack 是云端服务
• 官方标识：找 🎖️
• 结果：你会看到 Slack 的官方 MCP 服务器

第五步：注意那些“聚合器”分类

在分类列表的最前面，有一个 🔗 - Aggregators。这个分类里的服务器比较特殊——它们本身不提供单一功能，而是把多个 MCP 服务器打包成一个。比如 1mcp/agent 这个项目，你装一个它，就能同时访问文件系统、数据库、GitHub 等多个服务。

什么时候用聚合器？ 如果你刚开始接触 MCP，想快速体验多个功能，或者你的 AI 助手需要同时调用很多工具，聚合器能省去你一个个安装配置的麻烦。但如果你只需要一两个特定功能，直接装单独的服务器更轻量、更容易排查问题。

常见问题与排查

Q：我找到了一个服务器，但它没有操作系统标签，怎么办？ A：大部分服务器是跨平台的，没写标签通常意味着它支持所有主流系统。如果不确定，直接点进它的 GitHub 页面看 README，里面会写安装要求。

Q：分类太多，我找不到想要的功能怎么办？ A：用页面搜索（Ctrl+F）搜关键词。比如你想找“能发邮件的”，搜“email”或“mail”。如果搜不到，可能这个功能还没被收录，或者它藏在某个分类的角落里。你也可以去 Glama 的网页版目录 搜，那个搜索功能更友好。

Q：同一个分类下有多个类似的服务器，怎么选？ A：优先选带 🎖️ 官方标记的。如果没有官方版，就看哪个项目的 star 数多、最近有更新（看 GitHub 页面的“Last commit”日期）。如果还拿不准，两个都试试也不费事——MCP 服务器的安装通常就一行命令。

一个小练习

现在你可以自己试试：假设你想让 AI 能帮你查天气（就像上一章那样），用我们刚学的方法，从目录里找到对应的分类和服务器。提示一下：天气属于“环境与自然”还是“搜索与数据提取”？答案在 🌳 - Environment & Nature 分类里，你会看到 modelcontextprotocol/weather 这个官方服务器。

等你熟练了这套“看分类→读标签→筛条件”的流程，再打开那个 README，就不会觉得眼花缭乱了。下一章我们会挑一个具体的本地服务器，把它装起来，让 AI 真的能操作你电脑上的文件。

让 AI 直接操作你的文件：装一个文件系统服务器

上一章我们让 AI 助手查了天气，但那只是调用了一个远程 API。如果能让 AI 直接读写你电脑上的文件——比如自动整理下载文件夹、批量重命名、或者帮你把 Markdown 笔记转成 HTML——那才是真正解放双手。这一章我们就来装一个本地文件系统 MCP 服务器，让 AI 能像你一样操作文件。

前置条件

• 你已经安装了 Node.js（版本 18+）和 npm
• 你有一个支持 MCP 的客户端（比如 Claude Desktop，或者上一章用的测试环境）
• 你大概知道终端怎么打开（别怕，就复制粘贴几行命令）

第一步：找到合适的文件系统服务器

打开 Awesome MCP Servers 的页面，找到 File Systems 分类（就是那个 📂 图标）。这里有好几个选择，但最常用的是 modelcontextprotocol/filesystem——它是官方维护的，稳定且功能完整。

这个服务器能做的事情包括：

• 读取文件内容
• 写入/创建新文件
• 列出目录结构
• 移动、复制、删除文件
• 搜索文件

基本上你平时在文件管理器里能做的，它都能通过 AI 帮你做。

第二步：安装服务器

打开终端，找个你喜欢的目录（比如 ~/mcp-servers），然后运行：

npx @anthropic-ai/mcp-filesystem@latest

等等，别急着回车。这个命令会直接启动服务器，但我们得先告诉它允许访问哪些目录。就像你不会让陌生人随便翻你家抽屉一样，文件系统服务器也需要你指定它能碰哪些文件夹。

正确的做法是：

npx -y @anthropic-ai/mcp-filesystem@latest /Users/你的用户名/Documents /Users/你的用户名/Desktop

这里 -y 参数是自动确认安装（省得它问你"你确定要装吗"），后面跟的路径就是允许访问的目录。你可以加多个路径，用空格隔开。

注意： 路径要用绝对路径。Windows 上就是 C:\Users\你的用户名\Documents 这样。

第三步：验证服务器是否跑起来了

运行上面的命令后，终端应该会显示类似这样的输出：

Starting MCP filesystem server...
Allowed directories: /Users/你的用户名/Documents, /Users/你的用户名/Desktop
Server running on stdio

如果看到报错说 command not found 或者 npx: not found，说明 Node.js 没装好，回去检查一下。如果报 EACCES: permission denied，说明你给的路径没有读取权限——检查路径拼写，或者换个你有权限的文件夹。

第四步：配置到 Claude Desktop

光在终端里跑起来还不够，我们要让 AI 助手能调用它。打开 Claude Desktop 的配置文件（位置取决于你的系统）：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

如果文件不存在，就新建一个。然后写入：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-filesystem@latest",
        "/Users/你的用户名/Documents",
        "/Users/你的用户名/Desktop"
      ]
    }
  }
}

注意：路径要换成你自己的。如果你在 Windows 上，路径里的反斜杠要写成双反斜杠或者正斜杠，比如 "C:/Users/你的用户名/Documents"。

保存文件后，完全退出 Claude Desktop 再重新打开（光关窗口不行，要右键退出）。打开后你应该能在设置里看到 "filesystem" 这个工具已经激活了。

第五步：实战测试——让 AI 整理你的桌面

现在来点实际的。打开 Claude Desktop，输入：

"请列出我桌面上的所有文件，并按文件类型分类"

Claude 会调用文件系统服务器，读取你桌面的目录结构，然后给你一个分类清单。如果一切正常，你会看到类似这样的回复：

好的，我来查看你的桌面文件。

📄 文档类：
- 项目计划.docx (245KB)
- 会议纪要.txt (12KB)

🖼️ 图片类：
- 截图2024-01-15.png (1.2MB)
- 壁纸.jpg (3.5MB)

📦 压缩包：
- 备份.zip (45MB)

接下来你可以试试更高级的操作：

"把桌面上所有 .png 文件移动到 Documents/screenshots 文件夹里"

Claude 会先检查目标文件夹是否存在，如果不存在就创建，然后逐个移动文件。每一步它都会告诉你进展。

安全提示： 文件操作是不可逆的。如果你担心 AI 误操作，可以先只给一个测试文件夹的权限，比如新建一个 ~/mcp-test 目录，只把这个目录加到配置里。

常见问题排查

Q: 启动时报错 "Cannot find module '@anthropic-ai/mcp-filesystem'" A: 网络问题导致 npm 没下载成功。试试先手动安装：npm install -g @anthropic-ai/mcp-filesystem，然后再用 npx 启动。

Q: AI 说 "没有权限访问该文件" A: 检查配置文件里的路径是否写对了，而且这个路径必须在启动时指定的允许目录列表里。如果你后来改了配置，记得重启 Claude Desktop。

Q: 中文文件名显示乱码 A: 这是终端编码问题，不影响实际功能。在 macOS/Linux 上可以试试先设置 export LANG=zh_CN.UTF-8 再启动。

Q: 我想让 AI 访问整个硬盘 A: 强烈不建议。给 AI 的权限越少越安全。如果你确实需要，可以指定根目录 /（Linux/macOS）或 C:\（Windows），但请三思——AI 一个不小心就能把你的系统文件删了。

小技巧：用环境变量控制路径

如果你经常换项目，不想每次改配置文件，可以用环境变量：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-filesystem@latest",
        "${HOME}/projects"
      ]
    }
  }
}

这样只要改 HOME 环境变量就能切换工作目录。不过要注意，有些系统不支持在 JSON 里直接解析环境变量，更稳妥的做法是在启动脚本里处理。

现在你的 AI 助手已经能读写本地文件了。下一章我们会把它连到云端服务，让 AI 既能操作你的文件，又能调用 GitHub API——到时候你就知道什么叫真正的"万能工具库"了。

好，上一章我们折腾了本地文件系统，让 AI 能读写你电脑上的文件。这一章我们换个方向，让 AI 去调用 GitHub 的 API——这样它就能帮你查仓库信息、看 issue、甚至创建 PR，而你连浏览器都不用打开。

为什么需要云端服务器？

想象一下，你正在写代码，突然想看看某个开源项目的最新 release 版本。正常流程：打开浏览器 → 登录 GitHub → 搜索仓库 → 点开 Releases 页面。如果让 AI 助手来做，它只需要一个命令就能把结果甩给你。这就是云端 MCP 服务器的价值——它充当了 AI 和远程 API 之间的桥梁。

前置条件

在开始之前，确保你已经：

• 安装了 Node.js（版本 18+，可以用 node -v 检查）
• 有一个 GitHub 账号（免费的就行）
• 上一章配置好的 Claude Desktop（或者任何支持 MCP 的客户端）

第一步：找到 GitHub MCP 服务器

打开 Awesome MCP Servers 的页面，找到「Version Control」分类。你会看到好几个 GitHub 相关的服务器，但最常用的是 github/github-mcp-server——这是 GitHub 官方维护的，靠谱。

你也可以直接在终端里用一行命令启动它，不需要手动下载任何东西：

npx -y @github/github-mcp-server

第一次运行会下载依赖，稍等十几秒。如果看到类似这样的输出，说明启动成功了：

Starting MCP server...
Listening for messages...

注意：这个命令会一直运行，直到你按 Ctrl+C 停止。我们后面会把它配置到 Claude Desktop 里，让它后台运行。

第二步：生成 GitHub Personal Access Token

要让服务器能调用 GitHub API，你需要一个访问令牌。这就像一把钥匙，告诉 GitHub "我是谁，我能做什么"。

1. 打开 GitHub，点击右上角你的头像 → Settings
2. 在左侧菜单找到「Developer settings」→「Personal access tokens」→「Tokens (classic)」
3. 点击「Generate new token (classic)」
4. 给你的令牌起个名字，比如 "mcp-server"
5. 在权限选择里，勾上这些（按需选择，最少够用就行）：
   • repo（访问公开和私有仓库）
   • read:org（读取组织信息）
   • read:user（读取用户信息）
6. 点击底部的「Generate token」
7. 立刻复制生成的令牌（一串以 ghp_ 开头的字符串），关掉页面后就再也看不到了

把令牌保存到一个安全的地方，比如密码管理器。我们马上要用。

第三步：配置 Claude Desktop

现在我们要把 GitHub MCP 服务器加到 Claude Desktop 的配置里。找到你的配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

用文本编辑器打开它，你会看到类似这样的内容（如果之前配置过文件系统服务器）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/your/folder"
      ]
    }
  }
}

现在加上 GitHub 服务器的配置。在 mcpServers 对象里添加一个新条目：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/your/folder"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@github/github-mcp-server"
      ],
      "env": {
        "GITHUB_TOKEN": "你的令牌"
      }
    }
  }
}

把 "你的令牌" 替换成刚才复制的那一串 ghp_...。保存文件。

常见报错：如果忘记加 env 字段，或者令牌写错了，Claude 启动时会报错 "Failed to start MCP server: github"。检查一下令牌有没有多余的空格或换行。

第四步：重启 Claude 并测试

关闭 Claude Desktop 再重新打开。在聊天框里输入：

帮我看看 facebook/react 仓库的最新 release 版本是什么？

如果一切正常，Claude 会调用 GitHub API，然后返回类似这样的结果：

facebook/react 的最新 release 版本是 v18.3.1，发布于 2024年4月26日。
主要更新包括：
- 修复了一些内存泄漏问题
- 改进了 Strict Mode 下的行为
- 更新了相关文档

如果没反应：检查 Claude 窗口右上角有没有一个锤子图标？点一下，看看「Connected MCP Servers」里有没有 github。如果没有，说明配置没生效，回去检查 JSON 格式（比如逗号有没有漏掉）。

第五步：玩点更高级的

现在你已经能查信息了，试试更复杂的操作。比如，让 AI 帮你创建一个 issue：

在 facebook/react 仓库创建一个 issue，标题是 "测试：MCP 服务器真方便"，内容写 "这是通过 MCP 服务器自动创建的 issue。"

Claude 会调用 GitHub 的 Issues API，几秒钟后你就能在 https://github.com/facebook/react/issues 看到新创建的 issue（当然，别真的在别人的仓库乱发，找个自己的测试仓库试试）。

小技巧：如果你有自己的私有仓库，可以这样测试：

在我的私有仓库 my-test-repo 里，列出所有 open 状态的 issue。

只要你的令牌有 repo 权限，就能访问私有仓库。

常见问题排查

Q: 报错 "401 Unauthorized" A: 令牌过期了或者权限不够。去 GitHub 重新生成一个，确保勾选了 repo 权限。

Q: 报错 "403 rate limit exceeded" A: GitHub API 有调用频率限制（未认证每小时 60 次，认证后 5000 次）。等一会儿再试，或者检查是不是有程序在疯狂调用。

Q: 报错 "npx: command not found" A: Node.js 没装好。运行 node -v 和 npm -v 确认版本，重新安装 Node.js。

Q: Claude 说 "我没有权限执行这个操作" A: 令牌的权限范围不够。去 GitHub 重新生成，勾上需要的权限（比如 repo 或 admin:org）。

一个完整的实战场景

假设你是一个开源项目的维护者，每天要处理很多 issue。你可以这样用：

1. 列出我的仓库 awesome-project 里所有标记为 "bug" 的 issue
2. 找到最旧的那个，看看内容是什么
3. 如果它已经超过 30 天没更新，帮我回复 "这个 bug 还在吗？如果一周内没有回复，我会关闭它。"
4. 然后给它打上 "needs-reply" 标签

整个过程不需要打开浏览器，全在聊天框里完成。是不是感觉效率提升了一大截？

下一章我们会让 AI 同时使用多个工具——比如一边查数据库，一边调用 GitHub API，一边操作文件系统。那才是真正的"万能工具库"。

好，上一章我们让 AI 助手能操作文件系统，这一章再给它接上数据库，让它既能读写文件，又能查数据库。想象一下，你问 AI：“帮我查一下上个月销售额最高的客户，然后把结果存成一个 CSV 文件”——如果它只能干其中一件事，你就得手动切换工具；如果两个都能干，一句话就搞定。

这一章我们就来配置一个同时拥有文件系统和数据库工具的 AI 助手。我们选两个最典型的服务器：一个是上一章用过的文件系统服务器（比如 @anthropic/mcp-filesystem），另一个是 SQLite 数据库服务器（比如 @anthropic/mcp-sqlite）。把它们塞进同一个 AI 客户端（比如 Claude Desktop），就能让 AI 同时调用这两个工具。

前置条件：你已经装好了 Claude Desktop（或者任何支持 MCP 的客户端），并且至少成功跑通过一个 MCP 服务器（比如上一章的文件系统服务器）。如果你还没装，先回去看第 2 章。

---

第一步：确认两个服务器都能单独跑通

先别急着组合，我们确保每个服务器自己就能正常工作。打开终端，分别测试：

# 测试文件系统服务器（假设你用的是 @anthropic/mcp-filesystem）
npx -y @anthropic/mcp-filesystem /tmp/test-fs

# 测试 SQLite 服务器（假设你用的是 @anthropic/mcp-sqlite）
npx -y @anthropic/mcp-sqlite /tmp/test.db

如果两个命令都能正常启动（不会报错退出），说明它们各自没问题。如果其中一个报错，比如 command not found 或者 port already in use，先解决那个服务器的单独问题（参考第 10 章）。

预期结果：两个服务器都在终端里挂着，等待 AI 客户端连接。

---

第二步：在 Claude Desktop 配置里同时注册两个服务器

Claude Desktop 的配置文件通常叫 claude_desktop_config.json，位置在：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

打开这个文件，你会看到类似这样的结构（如果之前配置过文件系统服务器）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-filesystem",
        "/tmp/test-fs"
      ]
    }
  }
}

现在我们要加第二个服务器。在 mcpServers 对象里再加一个键值对：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-filesystem",
        "/tmp/test-fs"
      ]
    },
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-sqlite",
        "/tmp/test.db"
      ]
    }
  }
}

注意：每个服务器都有一个唯一的名称（这里是 filesystem 和 sqlite），这个名字可以随便起，但最好有意义。command 和 args 就是你在终端里跑的那个命令拆开来的。

预期结果：保存文件后，重启 Claude Desktop。你应该在设置里看到两个服务器都显示为“已连接”。

---

第三步：验证 AI 能否同时识别两个工具

重启 Claude Desktop 后，随便问一句：“你能用哪些工具？”或者直接问：“帮我列出当前目录的文件，然后查询 SQLite 数据库里有哪些表。”

如果配置正确，AI 应该会回答类似这样：

• 文件系统工具：read_file, write_file, list_directory 等
• SQLite 工具：query, execute, list_tables 等

如果 AI 只提到一个工具，说明另一个服务器没连上。检查配置文件的 JSON 格式是否正确（比如有没有漏掉逗号），或者看 Claude Desktop 的日志（通常在 ~/Library/Logs/Claude/ 下）。

常见报错：如果配置文件里两个服务器用了同一个端口（比如 SQLite 服务器默认用 8080，文件系统服务器也用了 8080），就会冲突。解决方法：给其中一个服务器指定不同的端口，比如在 args 里加 --port 8081。

---

第四步：实战演练——查数据库并导出结果

现在来一个真实场景：假设你有一个 SQLite 数据库 /tmp/sales.db，里面有一张 orders 表，你想查“2024 年销售额最高的前 5 个客户”，然后把结果存成 CSV 文件。

先确保数据库里有数据。如果还没有，可以自己建一个测试表：

-- 在 SQLite 里执行
CREATE TABLE orders (
  id INTEGER PRIMARY KEY,
  customer TEXT,
  amount REAL,
  date TEXT
);
INSERT INTO orders VALUES (1, '张三', 1200, '2024-03-01');
INSERT INTO orders VALUES (2, '李四', 2500, '2024-03-02');
INSERT INTO orders VALUES (3, '王五', 800, '2024-03-03');

然后对 AI 说：“帮我查一下 orders 表里销售额最高的前 5 个客户，把结果保存到 /tmp/top_customers.csv。”

AI 应该会：

1. 调用 SQLite 的 query 工具执行 SQL：SELECT customer, SUM(amount) as total FROM orders GROUP BY customer ORDER BY total DESC LIMIT 5
2. 拿到结果后，调用文件系统的 write_file 工具把结果写成 CSV 格式

如果一切顺利，你会看到 /tmp/top_customers.csv 文件被创建，内容类似：

customer,total
李四,2500
张三,1200
王五,800

注意：AI 可能不会自动把结果格式化成 CSV（它可能直接写 JSON 或文本）。你可以明确要求：“请用 CSV 格式，第一行是列名。”

---

第五步：处理组合使用时的常见问题

问题 1：AI 不知道该用哪个工具 有时候 AI 会搞混，比如你想查数据库，它却去读文件。这时候你可以明确指定：“用 SQLite 工具执行这个查询。” 或者更直接：“调用 query 工具。”

问题 2：工具调用顺序出错 比如 AI 先写文件，再查数据库，但写文件时数据库还没查完。这通常不会发生，因为 AI 会按顺序执行。但如果出现，你可以说：“先查数据库，拿到结果后再写文件。”

问题 3：路径问题 文件系统服务器和数据库服务器可能对路径的理解不同。比如文件系统服务器用 /tmp/test-fs 作为根目录，而 SQLite 服务器用 /tmp/test.db 作为数据库文件。确保路径一致，或者用绝对路径。

---

小技巧：用聚合服务器简化配置

如果你觉得手动配置多个服务器很麻烦，可以试试聚合服务器（Aggregators）。比如 1mcp/agent 这个服务器（在 Awesome MCP Servers 的 Aggregators 分类里），它可以把多个 MCP 服务器合并成一个。配置方式类似：

{
  "mcpServers": {
    "aggregator": {
      "command": "npx",
      "args": [
        "-y",
        "1mcp/agent",
        "--servers", "filesystem,sqlite"
      ]
    }
  }
}

这样你只需要配置一个服务器，它内部会帮你管理多个子服务器。不过聚合服务器还在早期阶段，可能不如手动配置稳定。

---

总结

这一章你学会了：

1. 在同一个 AI 客户端里配置多个 MCP 服务器
2. 让 AI 同时使用文件系统和数据库工具
3. 处理组合使用时的常见问题

现在你的 AI 助手已经能同时读写文件和查询数据库了。下一章我们会深入理解服务器标签，帮你快速判断一个服务器是干什么的、能不能在你的系统上跑。

逛过菜市场的人都知道，每个摊位前都挂着价格牌、产地标签、新鲜度标识。你一眼扫过去，就能判断这家的西红柿是本地大棚的还是外地运来的，是今天早上刚摘的还是昨天剩的。Awesome MCP Servers 的列表里，每个服务器前面也挂着一排小标签——那些看着像 emoji 的符号，就是帮你快速判断"这玩意儿能不能在我电脑上跑"的关键信息。

如果你跳过这些标签直接选服务器，大概率会遇到这种情况：明明照着教程装了一个看起来很牛的服务器，结果终端报错"Python 版本不对"，或者"这个服务只支持 macOS，你 Windows 用户洗洗睡吧"。标签就是帮你避坑的。

标签长什么样？

打开 Awesome MCP Servers 的 README，随便找一个服务器条目，你会看到类似这样的东西：

- [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) 📇 🏠 🍎 🪟 🐧

这一串符号就是标签。它们分成四类，按顺序排列：

1. 语言标签（第一个符号）：服务器用什么语言写的
2. 范围标签（第二个符号）：服务器是跑在本地的还是连云端的
3. 操作系统标签（第三个及之后）：支持哪些操作系统
4. 官方标识（如果有的话，放在最前面）：🎖️ 表示这是官方出品

咱们一个一个拆开看。

语言标签：这玩意儿用什么写的？

你不需要成为每种语言的专家，但知道服务器用什么写的能帮你预判两件事：安装难度和依赖要求。

符号	语言	你需要注意什么
📇	TypeScript / JavaScript	最常见，用 npx 就能跑，基本不需要额外安装
🐍	Python	需要 Python 3.8+，可能要用 pip install
🏎️	Go	需要 Go 编译器，或者直接下载编译好的二进制文件
🦀	Rust	需要 Rust 工具链，编译可能慢一点
#️⃣	C#	需要 .NET 运行时
☕	Java	需要 JRE 或 JDK
🌊	C/C++	需要编译器和系统库，新手慎选
💎	Ruby	需要 Ruby 解释器

实战技巧：如果你是新手，优先选 📇（TypeScript）或 🐍（Python）的服务器。它们生态最成熟，遇到问题网上能搜到的解决方案也最多。看到 🌊（C/C++）或 🦀（Rust）的服务器，除非你特别需要那个功能，否则先绕道走——编译环境配置能让你折腾一整天。

范围标签：这玩意儿连的是本地还是云端？

这个标签最容易让人困惑。官方 README 里专门加了个说明，我帮你翻译成人话：

符号	含义	典型场景
🏠	本地服务	服务器和你电脑上装的软件对话，比如控制 Chrome 浏览器、读写本地文件
☁️	云端服务	服务器和远程 API 对话，比如查天气、调 GitHub API
📟	嵌入式系统	服务器跑在 IoT 设备或微控制器上，一般用户用不到

怎么判断该选哪个？

• 你想让 AI 帮你操作本地软件（比如打开浏览器、编辑文件）→ 选 🏠
• 你想让 AI 帮你查网上的数据（比如股票价格、天气预报）→ 选 ☁️
• 你想让 AI 帮你控制家里的智能灯泡 → 可能两个都要，看具体实现

容易踩的坑：有些服务器同时标了 🏠 和 ☁️，比如聚合类服务器（Aggregators 分类里的）。这意味着它既能连本地服务也能连云端 API，配置起来会复杂一些，但功能也更强大。

操作系统标签：这玩意儿能在我的电脑上跑吗？

这个最直白，但也最容易忽略。三个符号对应三大操作系统：

符号	操作系统
🍎	macOS
🪟	Windows
🐧	Linux

重要规则：如果一个服务器只标了 🍎，那你用 Windows 大概率跑不起来。别问我怎么知道的——我当初看到个"文件系统操作"服务器，觉得功能很香，没看标签直接装，结果发现它依赖 macOS 的 osascript 命令，Windows 上根本不存在。

特殊情况：

• 有些服务器三个系统都标了（🍎 🪟 🐧），说明作者测试过全平台兼容
• 有些只标了两个，比如 🍎 🐧，说明 Windows 用户暂时用不了
• 如果没标任何操作系统符号，通常默认全平台支持，但最好去 GitHub 仓库确认一下

官方标识：这玩意儿靠谱吗？

看到 🎖️ 这个符号了吗？它表示官方实现。什么意思呢？比如你想用 GitHub 的 MCP 服务器，如果看到 🎖️，说明这是 GitHub 官方团队维护的，不是某个第三方开发者自己写的。

为什么重要：

• 官方维护的服务器通常更稳定、更新更及时
• API 变更时会同步更新，不会突然失效
• 有官方技术支持，遇到问题可以提 issue

但别迷信：有些第三方实现的服务器功能反而更丰富。比如某个数据库的 MCP 服务器，官方版本只支持基本查询，第三方版本可能加了写入、备份、甚至可视化功能。先看功能描述，再看标签。

实战：用标签快速筛选

假设你现在想找一个能帮 AI 助手操作本地文件系统的服务器。打开 Awesome MCP Servers，找到 "File Systems" 分类，你会看到一堆条目。怎么快速挑？

第一步：看范围标签。你要的是本地操作，所以找 🏠。看到 ☁️ 的直接跳过——那是连云存储的，不是操作你电脑上的文件。

第二步：看操作系统标签。你用的是 Windows，所以找带 🪟 的。如果某个服务器只标了 🍎 🐧，那它大概率在 Windows 上跑不了。

第三步：看语言标签。你是新手，优先选 📇 或 🐍。看到 🦀 或 🌊 的，除非你特别想挑战自己，否则先放一放。

第四步：看有没有 🎖️。如果有官方实现，优先考虑。但如果没有，也别慌——看看 GitHub 仓库的 star 数和最近更新时间，也能判断质量。

这样筛选下来，原本几十个服务器可能就剩下两三个了。再点进去看看 README，基本就能确定选哪个。

常见误区

误区一：标签越多越好。看到同时标了 🏠 和 ☁️ 的服务器就觉得功能强大。实际上，这种服务器配置起来更复杂，你需要同时配置本地环境和云端 API 密钥。选适合你当前需求的，不是功能最多的。

误区二：忽略语言标签。觉得反正都是装，Python 和 TypeScript 有什么区别？区别大了——Python 服务器可能要求你装 pip 包，TypeScript 服务器可能用 npx 一键启动。选你熟悉语言的服务器，能省一半调试时间。

误区三：以为没标操作系统就全支持。有些作者懒得标，或者只在自己电脑上测试过。最好去 GitHub 仓库的 Issues 里搜一下你的操作系统关键词，看看有没有人遇到过兼容性问题。

一个小练习

打开 Awesome MCP Servers 的 README，找到 "Databases" 分类。随便挑三个服务器，看看它们的标签组合。试着回答：

1. 这个服务器用什么语言写的？
2. 它是本地数据库还是云端数据库？
3. 能在你的操作系统上跑吗？
4. 是官方实现吗？

如果你能在一分钟内回答出这四个问题，恭喜你，你已经掌握了标签阅读技能。接下来选服务器的时候，先看标签再动手，能少走很多弯路。

你之前装 MCP 服务器，是不是得先 npm install 或者 pip install，然后手动配置路径？第 8 章要解决的就是这个麻烦——用 npx 直接启动服务器，连安装这一步都省了。你只需要一行命令，AI 助手就能立刻用上工具，像点外卖一样快。

前置条件

• 你已经装好了 Node.js（版本 >= 18），并且能在终端里运行 node -v 和 npx -v 看到版本号。
• 你有一个支持 MCP 的客户端（比如 Claude Desktop 或者 VS Code 的 MCP 插件）。
• 你大概知道 MCP 服务器是干嘛的（如果还不清楚，翻翻第 1 章）。

第一步：找到能用 npx 启动的服务器

不是所有 MCP 服务器都支持 npx 一键启动。你得看它的 README 里有没有类似这样的命令：

npx -y @some/mcp-server

或者

npx github:username/repo

在 Awesome MCP Servers 的列表里，很多 TypeScript/JavaScript 写的服务器（标签是 📇）都支持这种方式。比如我们之前用过的 @anthropic/mcp-server-weather，或者 @modelcontextprotocol/server-filesystem。

怎么找？ 打开 Awesome MCP Servers 网页版，搜索你想要的工具，点进去看 README 的 "Installation" 或 "Quick Start" 部分。如果它说 "Run with npx"，那就是了。

第二步：直接运行，不用安装

假设你想让 AI 助手能操作你的文件系统（比如读取、写入、删除文件）。按照第 4 章的做法，你得先 npm install -g @modelcontextprotocol/server-filesystem，然后配置路径。但用 npx 的话，你只需要在终端里运行：

npx -y @modelcontextprotocol/server-filesystem /path/to/your/folder

预期结果： 终端会显示一堆日志，最后停在类似 "Server started" 或 "Listening for messages" 的状态。这时候服务器已经在运行了，但还没连上 AI 助手。别关终端，保持它开着。

-y 是干嘛的？ 它自动回答 "yes"，跳过确认步骤。不加的话，npx 会问 "Do you want to install this package?"，你手动按回车也行。

第三步：把 npx 命令配置到客户端里

现在服务器在终端跑着，但你的 AI 助手还不知道它。你需要把这条命令告诉客户端。以 Claude Desktop 为例，打开它的配置文件（通常是 claude_desktop_config.json），在 mcpServers 里加一段：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Desktop"
      ]
    }
  }
}

注意： args 里的路径要写绝对路径，别用 ~ 或者相对路径。Windows 用户记得把反斜杠改成双反斜杠，比如 C:\\Users\\你的用户名\\Desktop。

保存文件，重启 Claude Desktop。现在你问它 "帮我看看桌面上有什么文件"，它就能直接读取了。

第四步：多个服务器一起跑

npx 的好处是每个服务器都是独立的进程，互不干扰。你可以同时启动好几个：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Desktop"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github", "--token", "你的GitHub令牌"]
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-sqlite", "--db-path", "/Users/me/data.db"]
    }
  }
}

预期结果： 重启客户端后，AI 助手能同时操作文件、查 GitHub 仓库、跑 SQL 查询。每个服务器都是独立的，一个挂了不影响其他的。

常见问题与排查

1. "npx 不是内部或外部命令"

这说明 Node.js 没装好，或者没加到 PATH 里。重新安装 Node.js（官网下载 LTS 版本），安装时勾选 "Add to PATH"。

2. "Error: Cannot find module '@modelcontextprotocol/server-filesystem'"

npx 会从 npm 仓库下载包，但有时候网络不好会失败。检查你的网络，或者试试先 npm config set registry https://registry.npmmirror.com 换成国内镜像。

3. 服务器启动后没反应，终端卡住

这是正常的。MCP 服务器通过标准输入输出（stdio）和客户端通信，所以它会一直等待消息。别关终端，也别按 Ctrl+C，除非你想停掉它。

4. 配置了但 AI 助手说找不到工具

检查配置文件里的 command 和 args 有没有写错。常见错误：路径写成了相对路径、忘了加 -y、或者 args 里忘了用数组（比如写成了字符串 "-y @modelcontextprotocol/server-filesystem"，这是错的）。

一个小例子串起来

假设你想让 AI 助手帮你管理一个待办事项列表，存在本地 SQLite 数据库里。用 npx 启动服务器：

npx -y @anthropic/mcp-server-sqlite --db-path /Users/me/todos.db

然后在 Claude Desktop 里配置：

{
  "mcpServers": {
    "todos": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-sqlite", "--db-path", "/Users/me/todos.db"]
    }
  }
}

重启后，你直接说："帮我创建一个待办事项表，包含 id、标题、状态和创建时间，然后加一条'买牛奶'的记录。" AI 助手就会自动执行 SQL 语句，创建表、插入数据。全程你不需要手动安装任何东西，一行 npx 搞定。

什么时候不用 npx？

• 服务器是用 Python 写的（标签 🐍）：npx 只能跑 JavaScript/TypeScript 项目，Python 的得用 uvx 或者 pip install。
• 服务器需要复杂的环境配置：比如要装系统级依赖（C++ 编译工具、数据库驱动），npx 搞不定。
• 你想长期使用某个服务器：npx 每次启动都会检查更新，如果网络慢或者想固定版本，还是 npm install -g 更稳。

总结： npx 是快速尝鲜和临时使用的利器，尤其适合在配置客户端时直接写命令，省去安装步骤。但如果你发现某个服务器每天都要用，而且版本稳定，那还是装到全局更省心。

你之前装过几个 MCP 服务器，比如文件系统那个，可能已经注意到：有些服务器装完就能用，有些却要你填一堆东西——API 密钥、数据库路径、端口号……这些“填的东西”就是环境变量和启动选项。这一章我们就专门搞定它们，让你以后看到任何服务器的配置说明都不慌。

先搞清楚：环境变量和启动选项到底是个啥？

想象一下你买了个智能音箱，第一次开机它问你：“你家 WiFi 密码是多少？”这个密码就是环境变量——每个用户都不一样，但音箱需要它才能联网工作。MCP 服务器也一样，它需要知道“你的 GitHub 令牌放哪”“你的数据库文件在哪”，这些信息通过环境变量传给它。

启动选项则是你告诉服务器“怎么跑”——比如“用调试模式启动”“监听 8080 端口”。它们通常跟在启动命令后面，像 --port 8080 这样。

第一步：找到服务器需要哪些配置

每个 MCP 服务器在 README 里都会告诉你它需要什么。以 GitHub 服务器为例（我们在第 5 章装过），它的 README 里会写：

Required:
- GITHUB_TOKEN: your personal access token

Optional:
- GITHUB_API_URL: custom API endpoint (default: https://api.github.com)

看到没？Required 就是必须填的，不填服务器直接罢工；Optional 是可选的，不填就用默认值。

实用技巧：如果 README 没写清楚，直接看服务器的 package.json 或 config 文件，里面通常有 env 或 args 字段。或者跑一下 npx @modelcontextprotocol/server-github --help，很多服务器会打印帮助信息。

第二步：在 Claude Desktop 里配置环境变量

Claude Desktop 的配置文件（claude_desktop_config.json）是管理环境变量的主战场。我们之前配置 GitHub 服务器时写过类似这样的代码：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

注意 env 字段——这就是放环境变量的地方。每个键值对对应一个环境变量。如果你有多个变量，继续往里加：

"env": {
  "GITHUB_TOKEN": "ghp_your_token_here",
  "GITHUB_API_URL": "https://api.github.com",
  "LOG_LEVEL": "debug"
}

常见报错：如果你填了环境变量但服务器还是报“Missing required environment variable”，检查两件事：

1. 变量名大小写对不对？GITHUB_TOKEN 和 github_token 是两回事。
2. 配置文件有没有保存？改完要重启 Claude Desktop 才生效。

第三步：通过启动参数传配置

有些配置不适合放环境变量，比如端口号、文件路径。这时候用启动参数（args 数组里的内容）。比如一个假设的数据库服务器：

{
  "mcpServers": {
    "my-db": {
      "command": "npx",
      "args": [
        "-y",
        "my-db-server",
        "--port", "5432",
        "--host", "localhost",
        "--db-path", "/data/mydb.sqlite"
      ],
      "env": {
        "DB_PASSWORD": "secret123"
      }
    }
  }
}

这里 --port 和 --host 是启动参数，DB_PASSWORD 是环境变量。为什么分开？因为密码放环境变量更安全（不会在进程列表里暴露），而端口号这种配置放参数更直观。

注意：有些服务器把 API 密钥也设计成启动参数（比如 --api-key），但安全起见，建议优先用环境变量。如果服务器只支持参数传密钥，确保你的配置文件权限设置正确（比如 chmod 600）。

第四步：处理路径类配置

文件系统服务器（第 4 章装过）需要你指定允许访问的目录。这通常通过启动参数或环境变量实现。看看它的典型配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects",
        "/Users/yourname/documents"
      ],
      "env": {}
    }
  }
}

路径直接写在 args 里，多个路径用空格隔开。注意路径要用绝对路径，相对路径容易出问题。

Windows 用户注意：路径要写成 C:\\Users\\yourname\\projects 或者用正斜杠 C:/Users/yourname/projects。反斜杠在 JSON 里需要转义。

第五步：处理敏感信息（API 密钥、密码）

永远不要把敏感信息硬编码在配置文件中提交到 GitHub。正确的做法是：

1. 用环境变量引用系统变量（如果你的系统支持）：

"env": {
  "GITHUB_TOKEN": "${GITHUB_TOKEN}"
}

但 Claude Desktop 的配置文件不一定支持变量展开，所以更稳妥的是：

2. 用 .env 文件（如果服务器支持）： 有些服务器会读取项目根目录的 .env 文件。你可以在启动命令里指定：

"args": ["-y", "server-name", "--env-file", "/path/to/.env"]

3. 最安全的方式：用密码管理器或密钥管理服务生成临时令牌，用完就撤销。

实用技巧：如果你在配置里写错了令牌，服务器启动时会报类似 401 Unauthorized 或 Authentication failed 的错误。这时去检查令牌是否过期、权限是否足够。

第六步：调试配置问题

配置完重启 Claude Desktop，如果服务器没启动，看日志。在 Claude Desktop 里：

• macOS：~/Library/Application Support/Claude/logs/
• Windows：%APPDATA%\Claude\logs\
• Linux：~/.config/Claude/logs/

找到对应的日志文件，搜索 Error 或 Failed。常见错误模式：

Error: connect ECONNREFUSED 127.0.0.1:5432

→ 端口被占用或服务没启动，检查 --port 参数。

Error: ENOENT: no such file or directory, open '/data/mydb.sqlite'

→ 路径写错了，检查 --db-path 参数。

Error: Missing required environment variable: GITHUB_TOKEN

→ 环境变量没传对，检查 env 字段。

小例子串一串：配置一个带数据库和缓存的服务器

假设你要装一个“笔记助手”服务器，它需要：

• 数据库连接（环境变量）
• 缓存目录（启动参数）
• API 密钥（环境变量）
• 调试模式（启动参数）

配置长这样：

{
  "mcpServers": {
    "notes-assistant": {
      "command": "npx",
      "args": [
        "-y",
        "@someone/notes-assistant",
        "--cache-dir", "/tmp/notes-cache",
        "--debug"
      ],
      "env": {
        "DB_CONNECTION_STRING": "postgresql://user:pass@localhost:5432/notes",
        "API_KEY": "sk-your-api-key-here",
        "NODE_ENV": "production"
      }
    }
  }
}

启动后，服务器会：

1. 用 DB_CONNECTION_STRING 连数据库
2. 把缓存写到 /tmp/notes-cache
3. 用 API_KEY 验证外部请求
4. 因为 --debug，日志会更详细

如果数据库连不上，检查 DB_CONNECTION_STRING 里的用户名密码对不对、数据库服务有没有启动。如果缓存报错，检查 /tmp/notes-cache 目录是否存在、有没有写权限。

最后一个小提醒

配置参数时，多看 README 里的“Configuration”或“Environment Variables”章节。如果 README 没写，直接去 GitHub 仓库的 Issues 里搜“env”或“config”，大概率有人问过同样的问题。实在不行，在服务器目录下跑 npx server-name --help，很多现代服务器会打印所有支持的参数。

下一章我们会专门处理启动时遇到的各种错误，但掌握了这一章的内容，你已经能解决 80% 的配置问题了。

第 10 章：解决常见启动错误：端口占用、依赖缺失与权限问题

你装好了一个 MCP 服务器，满心期待地敲下启动命令，结果终端里蹦出一堆红色报错。别慌，这太正常了。MCP 服务器本质上就是跑在你电脑上的程序，跟任何软件一样，会遇到端口被占、缺依赖、没权限这些老朋友。这一章我们就专门对付这三类最常见的启动错误，让你下次看到报错能淡定地"哦，又是这个"。

前置条件

• 已经装好 Node.js（版本 ≥ 18）或 Python（版本 ≥ 3.10），取决于你要启动的服务器类型
• 已经通过 npm install -g 或 pip install 装好了某个 MCP 服务器
• 终端能正常打开，知道怎么敲命令

第一步：端口占用——"地址已被使用"

这是最经典的错误。你启动服务器，终端报错类似：

Error: listen EADDRINUSE :::3000

或者：

Port 3000 is already in use

意思是：你想用的端口（比如 3000）已经被别的程序占用了。

怎么排查？

先看看谁占了端口。在终端里运行：

# macOS / Linux
lsof -i :3000

# Windows
netstat -ano | findstr :3000

你会看到一行输出，里面有进程 ID（PID）。比如 macOS 上可能看到：

COMMAND   PID   USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
node     12345  you    24u  IPv4 0x...      0t0  TCP *:3000 (LISTEN)

记下 PID，然后杀掉它：

# macOS / Linux
kill -9 12345

# Windows
taskkill /PID 12345 /F

更省事的办法：换个端口

如果你不想跟那个程序抢，直接让 MCP 服务器用别的端口。很多服务器支持 --port 参数：

npx @modelcontextprotocol/server-filesystem --port 3001 /path/to/dir

或者在配置文件的 env 字段里设置环境变量（具体看服务器文档）。

实用技巧：如果你经常遇到端口冲突，可以养成习惯，启动前先检查一下端口是否空闲。或者用 PORT=0 让系统自动分配一个空闲端口（不过这样你就得去日志里找实际端口号了）。

第二步：依赖缺失——"模块未找到"

你运行 npx 或 node 命令，终端报错：

Error: Cannot find module 'some-package'

或者：

Module not found: Error: Can't resolve 'express'

这通常是因为你跳过了安装步骤，或者安装过程中断了。

怎么解决？

先确认你确实装了依赖。如果你是用 npm install -g 全局安装的，试试：

npm list -g --depth=0

看看那个服务器在不在列表里。如果不在，重新安装：

npm install -g @modelcontextprotocol/server-filesystem

如果你是在项目目录里本地安装的（比如 clone 了仓库），确保你运行了：

cd /path/to/server
npm install

Python 服务器同理：

pip install mcp-server-sqlite

如果还报错，可能是 Node.js 或 Python 版本太老。检查版本：

node --version   # 需要 ≥ 18
python --version # 需要 ≥ 3.10

常见报错与排查：

• Error: Cannot find module '@modelcontextprotocol/sdk' → 说明服务器依赖的 SDK 没装。试试 npm install @modelcontextprotocol/sdk。
• Error: Cannot find module 'typescript' → 有些服务器需要 TypeScript 运行时。装一下：npm install -g typescript。
• Python 报 ModuleNotFoundError: No module named 'pydantic' → pip install pydantic。

实用技巧：如果 npm install 卡住或报网络错误，试试切换镜像源：

npm config set registry https://registry.npmmirror.com

用完了记得切回来：

npm config set registry https://registry.npmjs.org

第三步：权限问题——"拒绝访问"

你启动服务器，终端报错：

Error: EACCES: permission denied, open '/var/log/mcp-server.log'

或者：

Error: listen EACCES :::80

权限问题通常出现在两种情况：写文件没权限，或者用低端口（小于 1024）没权限。

怎么解决？

情况一：写文件权限

服务器想往某个目录写日志或数据，但当前用户没权限。最简单的办法：给那个目录加写权限：

chmod +w /path/to/directory

或者换个目录，比如用当前用户的家目录：

# 在服务器配置里把日志路径改成
/Users/你的用户名/logs/mcp-server.log

情况二：低端口权限

端口 80、443 这些需要 root 权限。如果你非要用 80 端口，可以：

sudo npx @modelcontextprotocol/server-filesystem --port 80 /path/to/dir

但更推荐的做法是用 1024 以上的端口，比如 8080、3000，省得每次都要 sudo。

情况三：npx 缓存权限

有时候 npx 缓存目录权限不对，导致启动失败。清理缓存：

npx clear-npx-cache

或者手动删缓存目录：

# macOS / Linux
rm -rf ~/.npm/_npx

# Windows
rmdir /s /q %APPDATA%\npm-cache\_npx

第四步：综合实战——一个真实场景

假设你想启动 @modelcontextprotocol/server-filesystem 来让 AI 访问你的文档目录。你敲了：

npx @modelcontextprotocol/server-filesystem /Users/me/Documents

结果报错：

Error: listen EADDRINUSE :::3000

你按第一步查了端口，发现是另一个 MCP 服务器占着。你杀掉它，再试：

npx @modelcontextprotocol/server-filesystem /Users/me/Documents

又报错：

Error: Cannot find module '@modelcontextprotocol/sdk'

你按第二步装了依赖：

npm install -g @modelcontextprotocol/sdk

再试：

npx @modelcontextprotocol/server-filesystem /Users/me/Documents

这次成功了，终端显示：

MCP server running on stdio

完美。整个过程不到两分钟。

第五步：预防胜于治疗——启动前检查清单

下次启动 MCP 服务器前，花 10 秒过一遍这个清单：

1. 端口：你要用的端口空闲吗？lsof -i :端口号
2. 依赖：服务器需要的包都装了吗？npm list -g 或 pip list
3. 权限：服务器要写的目录你可写吗？ls -ld /目标目录
4. 版本：Node.js 或 Python 版本够新吗？node --version 或 python --version

养成这个习惯，90% 的启动错误都能提前避免。

遇到没见过的错误怎么办？

如果报错信息不在上面三类里，别慌。先看报错的前三行和最后三行——真正的错误原因通常在那里。然后复制报错信息去搜索引擎搜，大概率有人遇到过。MCP 服务器的报错通常很直白，比如 "Connection refused" 就是连不上，"Timeout" 就是超时了。

最后记住：报错不是你的错，是程序在告诉你它需要什么。读懂报错，你就离解决问题不远了。

好的，我们直接开始。上一章我们搞定了用 npx 一键启动服务器，现在问题来了：你手头可能有好几个服务器——一个查天气的，一个操作文件的，一个连数据库的。难道每次跟 Claude 聊天都要手动启动一遍？那也太累了。

这一章要解决的就是这个问题：把多个 MCP 服务器一次性注册到 Claude Desktop 里，让 Claude 自己决定什么时候调用哪个工具。你只需要配置一次，以后打开 Claude 就能直接用。

前置条件：你已经装好了 Claude Desktop 客户端（不是网页版），并且至少跑通过一个 MCP 服务器（比如第 2 章的天气服务器）。如果你还没装客户端，去 claude.ai/download 下载安装就行。

---

第一步：找到 Claude Desktop 的配置文件

Claude Desktop 的配置藏在你的电脑里，不同系统位置不一样：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

你可以用文本编辑器直接打开，但我建议用命令行确认一下文件存在。打开终端（macOS/Linux）或 PowerShell（Windows），输入：

# macOS
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows (PowerShell)
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json"

如果文件不存在，别慌——Claude Desktop 会在你第一次配置后自动创建。你直接新建一个空文件也行。

预期结果：要么看到一堆 JSON，要么看到 File not found 之类的提示。如果是空文件，里面可能只有一对大括号 {}。

---

第二步：理解配置文件的骨架

这个 JSON 文件的核心结构长这样：

{
  "mcpServers": {
    "服务器名字": {
      "command": "启动命令",
      "args": ["参数1", "参数2"]
    }
  }
}

• "服务器名字"：你随便起，比如 "weather"、"filesystem"，但最好用英文，别用空格。
• "command"：就是你在终端里敲的那个命令，比如 npx、uvx、node。
• "args"：命令后面的参数，每个参数单独一个字符串。

还记得第 2 章我们怎么启动天气服务器的吗？在终端里敲的是：

npx -y @anthropic-ai/mcp-weather-server

那对应的配置就是：

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-weather-server"]
    }
  }
}

关键点：-y 和包名要分开写，不能写成 "-y @anthropic-ai/mcp-weather-server" 一个字符串。JSON 数组里每个元素就是你在终端里敲的一个"单词"。

---

第三步：添加第一个服务器——天气

现在打开配置文件，把天气服务器加进去。用文本编辑器打开 claude_desktop_config.json，写入：

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-weather-server"]
    }
  }
}

保存文件。然后完全退出 Claude Desktop（不是最小化，是右键退出），再重新打开。

验证方法：在 Claude 的聊天框里输入"北京今天天气怎么样？"。如果 Claude 回答了你，并且消息旁边出现了一个小锤子图标（表示调用了工具），那就成功了。

常见报错：如果 Claude 说"我没有访问天气工具"，大概率是配置文件格式错了。检查 JSON 有没有多逗号、少引号。你可以用 jsonlint.com 粘贴验证。

---

第四步：添加第二个服务器——文件系统

光一个天气不够，我们再加一个能操作文件的服务器。从 Awesome MCP Servers 里挑一个文件系统服务器，比如 modelcontextprotocol/filesystem。

这个服务器需要指定一个允许访问的目录，不然 Claude 能读你整个硬盘，那太危险了。假设你想让 Claude 只能操作 ~/Documents/mcp-test 这个文件夹，先创建它：

mkdir -p ~/Documents/mcp-test

然后修改配置文件，在 mcpServers 里加一个新条目：

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-weather-server"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Documents/mcp-test"
      ]
    }
  }
}

注意：/Users/你的用户名/Documents/mcp-test 要换成你实际的路径。macOS 上就是 ~/Documents/mcp-test 展开后的完整路径。Windows 上类似 C:\Users\你的用户名\Documents\mcp-test。

保存，重启 Claude Desktop。

验证方法：在 Claude 里说"在 mcp-test 文件夹里创建一个叫 hello.txt 的文件，内容写'你好，世界'。"如果 Claude 照做了，去文件夹里看看文件是不是真的存在。

常见报错：如果 Claude 说"没有权限"或"路径不存在"，检查路径写对了没，以及文件夹是不是真的创建了。路径里的波浪号 ~ 不会被自动展开，必须写完整路径。

---

第五步：添加需要环境变量的服务器

有些服务器需要 API 密钥之类的环境变量。比如你想加一个 GitHub 服务器（第 5 章讲过），它需要 GITHUB_TOKEN。

配置文件里可以加 env 字段：

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-weather-server"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Documents/mcp-test"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "你的个人访问令牌"
      }
    }
  }
}

安全提醒：GITHUB_TOKEN 是敏感信息，别把这个配置文件传到 GitHub 上。如果你用 Git 管理配置，记得把 claude_desktop_config.json 加到 .gitignore 里。

验证方法：重启 Claude 后，问它"看看我的 GitHub 仓库列表"。如果它列出了你的仓库，说明环境变量生效了。

---

第六步：处理启动参数复杂的服务器

有些服务器启动时需要更多参数，比如数据库服务器要指定连接字符串。假设你要加一个 SQLite 数据库服务器（第 6 章提过），它可能需要指定数据库文件路径：

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/你的用户名/Documents/mcp-test/test.db"
      ]
    }
  }
}

这里 uvx 是 Python 生态里的一个工具，类似 npx。如果你没装 uvx，可以用 pip install uvx 安装，或者换成 npx 对应的包。

关键点：每个参数独立成字符串。--db-path 是一个，路径是另一个。别写成 "--db-path /path/to/db" 一个字符串。

---

第七步：完整配置示例

把上面这些都合起来，一个完整的配置文件大概长这样：

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-weather-server"]
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的用户名/Documents/mcp-test"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_你的令牌"
      }
    },
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/你的用户名/Documents/mcp-test/test.db"
      ]
    }
  }
}

保存，重启 Claude Desktop。现在 Claude 同时拥有天气查询、文件操作、GitHub API 和数据库查询四种能力。你可以问它："帮我查一下北京天气，然后把结果存到 test.db 的 weather_log 表里。"——Claude 会自己决定先调天气服务器，再调数据库服务器。

---

常见问题与排查

Q：重启 Claude 后，聊天框里没有出现工具图标？

A：检查配置文件 JSON 格式。常见错误：最后一个条目后面多了逗号，或者路径里的反斜杠没转义（Windows 要用 \\ 而不是 \）。

Q：某个服务器启动失败，其他服务器正常？

A：Claude Desktop 不会告诉你哪个服务器挂了。你可以单独在终端里运行那个服务器的启动命令，看有没有报错。比如 npx -y @anthropic-ai/mcp-weather-server 如果终端里报错，说明配置没问题，是服务器本身的问题。

Q：改了配置但没生效？

A：确保你完全退出了 Claude Desktop（菜单栏退出，不是关窗口），再重新打开。有些系统上，Claude 会在后台驻留，需要强制退出。

Q：Windows 路径怎么写？

A：用双反斜杠 C:\\Users\\你的用户名\\Documents\\mcp-test，或者用正斜杠 C:/Users/你的用户名/Documents/mcp-test。JSON 里反斜杠是转义字符，所以必须写两个。

---

小结

现在你的 Claude Desktop 已经是一个多工具智能助手了。配置文件的本质就是告诉 Claude："这些服务器都在后台等着，你需要的时候直接调用。" 你不需要手动启动任何东西，打开 Claude 就能用。

下一章我们会把这些工具组合起来，做一个真正能查数据库、发邮件、搜网页的实战项目。到时候你会发现，配置文件里多写几行，Claude 的能力就翻倍。

好，前面几章我们分别试了文件系统、GitHub API、数据库这些单个工具。但现实中的工作流很少只用一个工具——你可能需要先查数据库拿到客户信息，再搜网页找点背景资料，最后发一封邮件把结果汇总出去。这一章我们就来真的：把三个 MCP 服务器拼在一起，让 AI 助手一次性完成"查数据库 → 搜网页 → 发邮件"这条完整链路。

前置准备

在开始之前，确保你已经：

1. 装好了 Claude Desktop（或其他支持多 MCP 服务器的客户端）
2. 有 Claude Desktop 的配置文件（claude_desktop_config.json），上一章我们讲过怎么找到它
3. 有一个可用的 SQLite 数据库文件（随便建一个，或者用我们第 4 章用过的那个）
4. 一个 Gmail 账号（用来发邮件，后面会用到应用专用密码）

如果你还没准备好数据库，先花 30 秒建一个：

# 在桌面创建一个测试数据库
cd ~/Desktop
sqlite3 customer.db "CREATE TABLE customers (id INTEGER PRIMARY KEY, name TEXT, email TEXT, city TEXT);"
sqlite3 customer.db "INSERT INTO customers VALUES (1, '张三', 'zhangsan@example.com', '北京'), (2, '李四', 'lisi@example.com', '上海');"

好，现在开始搭。

第一步：选三个服务器

从 Awesome MCP Servers 的目录里挑三个最合适的：

• 数据库 → 用 sqlite-mcp（🗄️ Databases 分类，📇 TypeScript，🏠 Local）
• 搜网页 → 用 web-search-mcp（🔎 Search & Data Extraction 分类，📇 TypeScript，☁️ Cloud）
• 发邮件 → 用 gmail-mcp（💬 Communication 分类，📇 TypeScript，☁️ Cloud）

这三个都是 TypeScript 写的，用 npx 就能启动，不需要手动安装。而且它们各自只做一件事，组合起来正好覆盖"读数据 → 查信息 → 发通知"这个典型流程。

第二步：配置 Claude Desktop

打开你的 claude_desktop_config.json，把三个服务器都加进去。注意每个服务器的启动命令和参数：

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-sqlite-server",
        "--db-path",
        "/Users/你的用户名/Desktop/customer.db"
      ]
    },
    "web-search": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-web-search"
      ]
    },
    "gmail": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic/mcp-gmail",
        "--credentials-path",
        "/Users/你的用户名/.mcp/gmail-credentials.json"
      ]
    }
  }
}

这里有几个坑要注意：

• --db-path 后面的路径必须写绝对路径，别用 ~/Desktop/ 这种简写，Claude 不认
• Gmail 的 --credentials-path 指向一个 JSON 文件，这个文件需要你提前生成。去 Google Cloud Console 创建一个 OAuth 2.0 客户端 ID，下载 JSON 放到 ~/.mcp/ 目录下
• 三个服务器的名字（sqlite、web-search、gmail）可以随便起，但建议用有意义的英文名，方便后面在对话里引用

保存文件后，重启 Claude Desktop。如果一切正常，你会看到左下角出现三个小图标，分别代表三个服务器。鼠标悬停上去能看到它们各自提供了哪些工具。

第三步：测试每个服务器单独工作

先别急着组合，逐个确认每个服务器能正常响应。

测试数据库：

帮我查一下 customer.db 里有多少客户，列出他们的名字和城市。

如果配置正确，Claude 会调用 sqlite 服务器的 query 工具，返回两条记录：张三（北京）、李四（上海）。

测试搜索：

搜索一下最近关于 MCP 协议的新消息。

Claude 会调用 web-search 服务器的 search 工具，返回几条搜索结果。注意第一次用可能会弹浏览器让你授权，按提示操作就行。

测试邮件：

帮我发一封测试邮件到 zhangsan@example.com，主题是"测试"，内容写"这是一封来自 MCP 助手的测试邮件"。

第一次发邮件会跳 OAuth 授权页面，登录你的 Gmail 账号并授权。之后就不需要了。

如果三个都跑通了，恭喜，你已经有了一个"三合一"的工具箱。

第四步：组合使用——一个真实的场景

现在来点实际的。假设你是销售主管，每天要处理这样的任务：查一下北京客户的名单，搜一下他们公司的最新动态，然后给每个客户发一封个性化的跟进邮件。

直接对 Claude 说：

帮我完成以下工作：
1. 从 customer.db 里找出所有在北京的客户
2. 搜索这些客户所在行业的最新新闻
3. 根据搜索结果，给每个客户写一封简短的跟进邮件并发送

Claude 会依次执行：

1. 调用 sqlite 的 query 工具：SELECT * FROM customers WHERE city = '北京'
2. 拿到结果后，调用 web-search 的 search 工具，搜索"北京 科技行业 最新动态 2025"（它会根据上下文自动推断关键词）
3. 结合数据库里的客户姓名和搜索到的行业新闻，调用 gmail 的 send_email 工具，给每个客户发邮件

你可能会看到类似这样的输出：

已从数据库中找到 1 位北京客户：张三（zhangsan@example.com）
正在搜索北京科技行业最新动态...
搜索到 3 条相关新闻，其中提到 AI 应用落地加速
正在为张三撰写邮件...
邮件已发送至 zhangsan@example.com，主题为"关于 AI 应用的最新动态与您的业务机会"

整个过程不需要你手动切换工具，也不需要复制粘贴数据。Claude 自己会决定什么时候查数据库、什么时候搜网页、什么时候发邮件。

常见问题

问题：Claude 说"没有找到可用的工具" 检查配置文件里的服务器名字是否拼写正确，特别是大小写。重启 Claude Desktop 后，等几秒钟让服务器启动完成。

问题：邮件发送失败，提示 "Invalid grant" Gmail 的 OAuth 令牌过期了。删掉 ~/.mcp/gmail-credentials.json 文件，重新发一次邮件，会再次弹出授权页面。

问题：搜索返回的结果太少或太旧 可以明确告诉 Claude 搜索的关键词和时间范围，比如"搜索 2025 年北京科技行业的最新新闻，返回前 5 条"。

问题：数据库查询返回空结果 确认 --db-path 指向的文件确实存在，并且里面有数据。可以在终端里先跑一下 sqlite3 /path/to/your.db "SELECT * FROM customers" 验证。

一点小技巧

• 如果想让 Claude 按特定顺序执行任务，可以在指令里明确说"先查数据库，再根据结果搜索，最后发邮件"。虽然 Claude 通常能自己判断顺序，但明确指定可以减少误解
• 三个服务器同时启动会占用一些内存，如果你的电脑比较老，可以考虑只启动当前需要的服务器，用完了再关掉
• 邮件内容里可以要求 Claude 引用搜索到的新闻标题和链接，这样客户收到邮件会觉得你做了功课

现在你可以试着扩展这个组合了——比如再加一个文件系统服务器，把邮件内容同时保存到本地文件；或者加一个日历服务器，自动在发完邮件后创建跟进提醒。三个工具能做的事，远远不止三个。

好，你已经装了五六个 MCP 服务器，每个都能干点不一样的事。但问题来了：你怎么知道还有哪些好用的服务器？别人是怎么配的？遇到坑了去哪问？

这章我们就来解决这个问题——学会在社区里“淘”服务器、找教程、问问题。你不需要自己发明轮子，社区里已经有成千上万人踩过坑、写过教程、分享过配置。

第一步：找到那个“活的”目录

你之前看的 Awesome MCP Servers 仓库（GitHub 上那个）其实只是一个“快照”。它更新得再勤快，也赶不上社区里每天冒出来的新服务器。

真正的宝藏藏在它的网页版目录里：

https://glama.ai/mcp/servers

这个页面和 GitHub 仓库是同步的，但多了几个杀手级功能：

• 搜索框：直接搜“database”“slack”“github”就能找到对应服务器
• 按标签筛选：点一下“☁️ Cloud Service”就能只看云端服务器
• 看活跃度：能看到每个服务器最近有没有更新、有多少人用过

你打开这个页面，随便搜个“weather”，就能看到好几个天气相关的 MCP 服务器，每个都有简介、安装命令、配置示例。

第二步：从教程里“偷”配置

很多人卡在“装上了但不会配”这一步。别急，社区里已经有人把配置过程录成视频、写成文章了。

Awesome MCP Servers 的 README 里专门有个 Tutorials 章节，目前有三个好东西：

1. Tool Definition Quality Score (TDQS) — 一个帮你评估 MCP 服务器质量的标准，选服务器的时候可以参考
2. Model Context Protocol (MCP) Quickstart — 官方快速入门指南，讲的是最基础的用法
3. Setup Claude Desktop App to Use a SQLite Database — 一个 YouTube 视频，手把手教你配 SQLite 数据库服务器

这些教程的链接都在 README 的 Tutorials 部分。点进去看一遍，你就能学到别人是怎么配置的、遇到问题怎么排查的。

实用技巧：在 YouTube 上搜“MCP server tutorial”或者“Claude MCP setup”，你会发现更多教程。很多开发者会录屏分享他们的配置过程，比看文档直观多了。

第三步：加入社区，直接问人

文档和教程解决不了的问题，直接去问活人。社区有两个主要聚集地：

Reddit：r/mcp

https://www.reddit.com/r/mcp

这个子版块是 MCP 相关的讨论区。你可以在里面：

• 搜“error”看看别人遇到过的报错
• 发帖问“有没有能操作 Excel 的 MCP 服务器？”
• 看别人分享的“我配了个超好用的工具集”帖子

注意：发帖前先搜一下，大概率你的问题已经有人问过了。

Discord 服务器

https://glama.ai/mcp/discord

Discord 的好处是实时。你配到一半卡住了，截图发到 #help 频道，几分钟内就可能有人回复。而且很多 MCP 服务器的作者本人就在 Discord 里，可以直接问他们。

加入后建议：先看 #rules 和 #announcements 频道，了解基本规则。然后在 #introductions 打个招呼，说“我刚接触 MCP，想配个文件系统服务器”，大家会很热情地帮你。

第四步：看懂服务器标签，快速筛选

回到 Awesome MCP Servers 的 README，你会发现每个服务器前面都有几个小图标。这些不是装饰，是帮你快速判断“这个服务器适不适合我”的标签。

比如这个：

📇 ☁️ 🍎 🪟 🐧

意思是：

• 📇 — 用 TypeScript/JavaScript 写的
• ☁️ — 云端服务（调用远程 API）
• 🍎 🪟 🐧 — 支持 macOS、Windows、Linux

再看这个：

🐍 🏠 🍎

意思是：

• 🐍 — 用 Python 写的
• 🏠 — 本地服务（操作你电脑上的软件）
• 🍎 — 仅支持 macOS

常见标签速查：

图标	含义
🎖️	官方实现（开发者自己维护的）
🐍	Python 代码
📇	TypeScript/JavaScript 代码
🏎️	Go 代码
🦀	Rust 代码
☁️	云端服务（调远程 API）
🏠	本地服务（操作本地软件）
🍎	支持 macOS
🪟	支持 Windows
🐧	支持 Linux

怎么用：假设你用的是 Windows，只想找本地文件操作相关的服务器。那就扫一眼标签，找同时有 🏠 和 🪟 的。没有 🪟 的服务器在 Windows 上可能跑不起来，直接跳过。

第五步：从“聚合器”服务器开始探索

如果你不想一个一个装服务器，可以试试 Aggregators（聚合器）分类下的服务器。这些服务器把几十个甚至上百个工具打包成一个 MCP 服务器，装一个等于装了一堆。

比如 2s-io/sdk 这个聚合器，它集成了 180+ 个工具，包括天气查询、地图、专利搜索、论文检索、翻译、截图等等。安装命令很简单：

npx -y @2sio/mcp

装完之后，你的 AI 助手就能直接调用这 180 多个工具，不用一个一个配置。

注意：聚合器虽然方便，但有些工具可能需要付费（比如按次收费的 API）。用之前看清楚文档里的收费说明。

第六步：自己动手，搜一个你需要的服务器

现在我们来实战一下。假设你想找一个“能操作 GitHub”的 MCP 服务器。

1. 打开网页版目录：https://glama.ai/mcp/servers
2. 在搜索框输入 github
3. 你会看到好几个结果，比如 github/github-mcp-server（官方版）
4. 点进去看详情：有安装命令、配置示例、依赖说明

或者直接在 GitHub 上搜 mcp-server github，也能找到很多社区实现。

小技巧：搜的时候加上 awesome-mcp-servers 关键词，能过滤出被收录的、质量相对有保障的服务器。

常见问题

Q：我英语不好，看不懂英文教程怎么办？

A：用浏览器的翻译功能，或者用 AI 助手帮你翻译。另外 YouTube 上已经有中文的 MCP 教程了，搜“MCP 服务器 配置”试试。

Q：在 Reddit 或 Discord 上问问题，要注意什么？

A：先说清楚你的环境（操作系统、MCP 客户端版本、服务器名称），贴出完整的报错信息（不要只截图，把文字复制出来）。这样别人才能快速帮你定位问题。

Q：怎么判断一个服务器靠不靠谱？

A：看三点：① 有没有 🎖️ 官方标识；② GitHub 仓库的 star 数和最近更新时间；③ 有没有人用过并在社区里讨论过。

下一步

现在你知道去哪找服务器、怎么筛选、去哪问问题了。下一章我们会更进一步：如何把自己写的工具也做成 MCP 服务器，贡献回社区。但在此之前，建议你先去 Discord 或 Reddit 逛一圈，看看别人都在讨论什么，说不定能发现一些你之前不知道的好东西。

好，前面十几章我们一直在用别人做好的 MCP 服务器，从查天气到操作数据库，爽是爽，但有没有想过——这些服务器是谁写的？我能不能也写一个？或者，我看到一个不错的服务器，想给它加个功能，怎么搞？

这一章我们就来解决这两个问题：怎么给 Awesome MCP Servers 项目贡献代码，以及怎么从零开始写一个自己的 MCP 服务器。读完你会发现，这事儿没你想的那么难，甚至有点好玩。

先搞清楚贡献的几种方式

贡献不只是写代码。你翻翻 Awesome MCP Servers 的 README，会发现它本质上是一个精选列表，不是代码仓库。所以贡献方式主要有三种：

1. 提交新服务器：你写了一个 MCP 服务器，或者发现了一个列表里没有的好东西，把它加进去。
2. 修复/改进现有服务器：某个服务器有 bug，或者你想加个新功能，直接去那个服务器的仓库提 PR。
3. 改进 Awesome MCP Servers 本身：比如 README 的排版、分类、说明文字等。

我们一个一个来看。

方式一：提交新服务器到 Awesome MCP Servers

这是最直接的贡献方式。假设你写了一个能查快递物流的 MCP 服务器，想让全世界都用上。

第一步：检查是否已存在

先去 Glama.ai 的网页目录 搜一下，或者直接在 README 里 Ctrl+F 搜 "logistics"、"express" 之类的关键词。如果已经有了，就别重复造轮子了。

第二步：准备你的服务器信息

你需要提供以下内容：

• 仓库地址：比如 https://github.com/你的名字/express-mcp
• 标签：根据 README 里的 Legend，给你的服务器打上正确的标签。比如你的服务器是用 TypeScript 写的，那就是 📇；如果是调用远程 API 查物流，那就是 ☁️；支持 macOS 和 Windows，那就是 🍎 🪟。
• 简短描述：一句话说清楚它能干什么。比如 "MCP server for querying express delivery status across major carriers in China."

第三步：提交 Pull Request

1. Fork punkpeye/awesome-mcp-servers 这个仓库。
2. 在本地 clone 下来，找到对应的分类。物流应该放在哪个分类？看看 README 的分类列表，没有专门的 "Logistics"，但可以放在 "🚚 - Delivery" 下面，或者 "🛠️ - Other Tools and Integrations"。
3. 在对应分类下按字母顺序插入你的条目，格式参考已有的：

- [你的名字/express-mcp](https://github.com/你的名字/express-mcp) 📇 ☁️ 🍎 🪟 - MCP server for querying express delivery status across major carriers in China.

4. 提交 PR，在描述里说明你的服务器是干什么的、为什么应该被收录。

预期结果：项目维护者会 review 你的 PR，如果没问题就会 merge。之后你的服务器就会出现在 Awesome MCP Servers 的列表里，同步到 Glama.ai 的网页目录。

常见问题

• PR 被拒了怎么办？ 最常见的原因是重复、描述不清、或者服务器质量不够。看看维护者的反馈，改进后重新提交。
• 我的服务器还没写完，能提交吗？ 建议至少有一个能跑的最小可用版本，不然别人点进去发现啥都没有，体验不好。

方式二：给现有服务器贡献代码

这个更常见。比如你发现 filesystem 这个服务器不支持删除文件夹，你想加上这个功能。

第一步：找到仓库

在 Awesome MCP Servers 里找到那个服务器，点链接进去。比如 filesystem 服务器的仓库是 modelcontextprotocol/servers。

第二步：看贡献指南

大多数正经项目都有 CONTRIBUTING.md 文件，告诉你代码风格、测试要求、PR 流程等。没有的话，就看 README 里的说明。

第三步：写代码

假设你要给 filesystem 服务器加一个 delete_folder 工具。以 TypeScript 为例，你需要在 src/filesystem/index.ts 里添加：

import { z } from "zod";

// 定义工具参数
const DeleteFolderArgs = z.object({
  path: z.string().describe("要删除的文件夹路径"),
});

// 注册工具
server.tool(
  "delete_folder",
  "删除指定文件夹及其所有内容",
  DeleteFolderArgs.shape,
  async (args) => {
    const { path } = args;
    try {
      await fs.rm(path, { recursive: true, force: true });
      return {
        content: [{ type: "text", text: `文件夹 ${path} 已删除` }],
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: `删除失败: ${error.message}` }],
        isError: true,
      };
    }
  }
);

预期结果：代码写完后，运行 npm run build 确保编译通过，然后 npm test 跑一下测试。

第四步：提交 PR

1. Fork 那个仓库。
2. 创建一个新分支，比如 feat/add-delete-folder。
3. 提交你的改动，写清楚 commit message，比如 feat: add delete_folder tool to filesystem server。
4. 推送到你的 fork，然后提交 PR。

预期结果：维护者 review 后 merge，你的代码就进了官方版本。下次别人用 npx @modelcontextprotocol/server-filesystem 时，就能用上你加的功能了。

常见问题

• 测试跑不过怎么办？ 看看是不是环境问题，或者你的代码有 bug。本地先调通再提交。
• PR 很久没人理？ 可以礼貌地在 PR 下面 @ 一下维护者，或者在项目的 Discord 里问一下。

方式三：从零写一个自己的 MCP 服务器

这才是最有意思的部分。我们写一个最简单的 MCP 服务器：能查当前时间的。

第一步：初始化项目

mkdir time-mcp-server
cd time-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod

第二步：写服务器代码

创建 src/index.ts：

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// 创建服务器实例
const server = new Server(
  {
    name: "time-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// 定义工具：获取当前时间
const GetTimeArgs = z.object({
  timezone: z.string().optional().describe("时区，如 Asia/Shanghai，默认 UTC"),
});

server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_current_time") {
    const { timezone } = GetTimeArgs.parse(args);
    const now = new Date();
    const options: Intl.DateTimeFormatOptions = {
      timeZone: timezone || "UTC",
      year: "numeric",
      month: "2-digit",
      day: "2-digit",
      hour: "2-digit",
      minute: "2-digit",
      second: "2-digit",
    };
    const timeString = new Intl.DateTimeFormat("zh-CN", options).format(now);
    return {
      content: [{ type: "text", text: `当前时间: ${timeString}` }],
    };
  }

  throw new Error(`未知工具: ${name}`);
});

// 启动服务器
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Time MCP server running on stdio");

第三步：编译并测试

npx tsc src/index.ts --outDir dist --moduleResolution node --target ES2020 --module ES2022

然后创建一个测试脚本 test.js：

const { spawn } = require("child_process");
const server = spawn("node", ["dist/index.js"]);

server.stdout.on("data", (data) => {
  console.log("收到响应:", data.toString());
});

// 发送一个工具调用请求
server.stdin.write(
  JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "get_current_time",
      arguments: { timezone: "Asia/Shanghai" },
    },
  }) + "\n"
);

setTimeout(() => server.kill(), 2000);

预期结果：运行 node test.js，你应该能看到类似 收到响应: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"当前时间: 2025/01/15 14:30:22"}]}} 的输出。

第四步：发布到 npm

npm publish

预期结果：你的服务器就发布到 npm 上了，别人可以用 npx time-mcp-server 来启动。

第五步：提交到 Awesome MCP Servers

按照方式一的步骤，把你的服务器加到列表里。

实用技巧

• 用模板快速开始：很多 MCP SDK 提供了模板项目，比如 npm create @modelcontextprotocol/server 可以生成一个完整的脚手架。
• 测试工具定义：用 tools/list 方法可以列出你的服务器支持的所有工具，方便调试。
• 错误处理要友好：返回 isError: true 并给出清晰的错误信息，这样 AI 助手才能理解并尝试修复。

一个小例子串起来

假设你是个快递公司的开发者，公司内部有个查物流的 API。你写了一个 MCP 服务器，让 Claude 能直接查快递状态。然后你把它提交到 Awesome MCP Servers，其他公司的同事也能用。过了一个月，有个用户提 PR 说想加上批量查询功能，你 review 后 merge 了。现在这个服务器成了物流行业的标准工具。

这就是从使用者到贡献者的转变。你不再只是消费别人写好的东西，而是开始参与构建这个生态。而且说实话，看到自己的代码被列在 Awesome MCP Servers 里，还是挺有成就感的。

问题 1：安装某个 MCP 服务器时提示 command not found: npx 或 node: command not found，怎么办？

解答：
这是典型的 Node.js 环境缺失或未正确配置 PATH 的问题。

• 首先确认已安装 Node.js（版本 ≥ 18）：node -v
• 如果未安装，前往 nodejs.org 下载 LTS 版本。
• 安装后重启终端，再次尝试 npx -y <server-package>。
• 若仍报错，检查 npm bin -g 路径是否在 $PATH 中（Windows 用户需确保 Node.js 安装时勾选了“Add to PATH”）。

---

问题 2：运行 MCP 服务器时出现 Error: Cannot find module 'xxx' 或 Module not found。

解答：
通常是因为依赖未安装完整或使用了错误的包管理器。

• 如果服务器是 TypeScript/JavaScript 项目（📇 标记），先进入项目目录执行 npm install 或 yarn install。
• 如果是 Python 项目（🐍 标记），使用 pip install -r requirements.txt 或 uv pip install。
• 检查 package.json 或 pyproject.toml 中的依赖声明，确保版本兼容。
• 如果使用 npx 运行，确保网络畅通且 npm 缓存未损坏（可尝试 npm cache clean --force）。

---

问题 3：如何区分“本地服务”（🏠）和“云服务”（☁️）？我该选哪个？

解答：

• 本地服务（🏠）：MCP 服务器与本地安装的软件交互，例如控制 Chrome 浏览器、访问本地文件系统或 SQLite 数据库。适合需要离线运行或处理敏感数据的场景。
• 云服务（☁️）：MCP 服务器调用远程 API，例如天气查询、GitHub 操作或 OpenAI 接口。需要网络连接，通常有 API 密钥或计费限制。
• 选择建议：如果工具需要访问本地资源（如文件、数据库、浏览器），选本地；如果只需调用外部 API（如搜索、翻译、金融数据），选云服务。项目列表中的图标（🏠/☁️）已明确标注。

---

问题 4：为什么有些 MCP 服务器在 Windows 上运行失败，但在 macOS/Linux 上正常？

解答：
部分服务器依赖 Unix 特有的功能（如 fork()、pty、unix socket）或硬编码了路径分隔符。

• 查看项目 README 中的操作系统图标（🍎 macOS、🪟 Windows、🐧 Linux），确认是否支持 Windows。
• 如果未标注 Windows 支持，尝试在 WSL2（Windows Subsystem for Linux）中运行。
• 对于 Python 项目，确保使用 python 而非 python3（Windows 默认无 python3 别名）。
• 检查 package.json 中的 scripts 是否包含跨平台兼容的路径写法（如使用 path 模块而非字符串拼接）。

---

问题 5：我想同时使用多个 MCP 服务器，但客户端只支持一个配置，怎么办？

解答：
使用 聚合器（Aggregator） 类型的 MCP 服务器，例如 1mcp/agent 或 2s-io/sdk。

• 这些服务器可以将多个 MCP 服务合并为一个统一端点，客户端只需连接一个聚合器即可访问所有工具。
• 配置方式：在客户端（如 Claude Desktop）的 mcp.json 中，将聚合器设为唯一服务器，并在聚合器的配置中列出所有子服务器。
• 注意：聚合器可能引入额外延迟或计费（如基于 x402 微支付），请查看具体项目的文档。

---

问题 6：MCP 服务器和普通的 API 封装工具（如 LangChain Tool）有什么区别？

解答：

• MCP 服务器 遵循 Model Context Protocol 标准，提供统一的接口（tools/list、tools/call、resources/list 等），让 AI 模型（如 Claude、GPT）以标准化方式发现和调用能力。
• 普通 API 封装 通常需要手动编写工具定义、处理认证和错误，且与特定框架（如 LangChain）绑定。
• 优势：MCP 服务器可跨客户端复用（Claude Desktop、VS Code 插件、自定义应用），且支持动态资源发现（如文件系统、数据库表）。
• 劣势：MCP 生态仍在早期，部分服务器功能较简单；普通 API 封装可能更灵活（如自定义缓存、重试逻辑）。

---

问题 7：运行 MCP 服务器时提示 x402 或 micropayment required，这是什么？

解答：
这是基于 x402 协议 的微支付机制，用于按调用次数付费（通常每调用 0.01–0.05 美元）。

• 常见于聚合器或云服务（如 2s-io/sdk、coinopai-mcp）。
• 需要钱包（如 MetaMask）和 Base 链上的 USDC 余额。
• 首次使用会提示授权，后续自动扣费。
• 替代方案：如果不想付费，可寻找同类的免费服务器（如本地运行的 SQLite 服务器），或自行部署开源版本。

---

问题 8：如何为 MCP 服务器添加自定义工具或修改现有行为？

解答：

• 如果服务器是开源项目（绝大多数），可 fork 后修改代码。
• TypeScript 项目：编辑 src/tools/ 下的文件，重新编译（npm run build）后使用。
• Python 项目：修改 server.py 或 tools/ 目录，重启服务器即可。
• 框架辅助：使用 @modelcontextprotocol/sdk（TypeScript）或 mcp（Python）快速创建自定义服务器，参考项目中的 Frameworks 章节。
• 注意：修改后需更新 package.json 或 pyproject.toml 中的版本号，避免与官方版本冲突。