WorkBuddy进化-12：打通外部世界—自建MCP服务，让AI连接资源

一、先说清楚MCP是什么

前面11期，我们讲了技能、专家、浏览器自动化、定时任务。这些能力有一个共同特点：都在 WorkBuddy 内部运行。

但实际工作中，你的数据往往不在 WorkBuddy 里—在公司的数据库里、在第三方 API 里、在 Notion 文档里、在企业微信里。MCP（Model Context Protocol，模型上下文协议）就是解决这个问题的。它是 AI 工具与外部服务交互的标准协议。一句话：

• 没有 MCP：WorkBuddy 只能操作本地文件和内置工具
• 有了 MCP：WorkBuddy 可以直接查数据库、调 API、读写外部系统

把它想象成 WorkBuddy 的"USB 接口"——插上什么设备，就多了什么能力。

二、MCP 是怎么工作的

MCP 采用客户端-服务端架构：

WorkBuddy（MCP 客户端）↓ 通过 MCP 协议通信MCP Server（你配置的服务）↓ 执行实际操作外部系统（数据库 / API / 文件系统）

你只需要写一个配置文件（mcp.json），告诉 WorkBuddy "有一个 MCP 服务在哪儿、怎么启动它"。WorkBuddy 会自动连接、自动发现它提供了哪些工具、在需要时自动调用。

整个过程对你是透明的——你在对话框里用自然语言说"查一下数据库里上个月的销售额"，WorkBuddy 自动调用对应的 MCP Server 去查数据库，然后把结果返回给你。

三、实战一：配置文件系统 MCP

这是最基础的 MCP，让 WorkBuddy 能读写你指定的目录。

第一步：确认 Node.js 版本

MCP 核心包要求 Node.js >= 18。终端输入：

# 查看当前 Node.js 版本号，确保 >= 18node --version

如果版本低于 18，先升级。

第二步：编写 mcp.json

在 WorkBuddy 配置目录下创建或编辑 mcp.json（通常位于 ~/.workbuddy/mcp.json）：

{// 【顶层对象】整个 MCP 配置文件的根，必须是一个合法的 JSON 对象"mcpServers": {// 【服务注册区】每个 key 是一个 MCP 服务的名称（自定义，保持唯一即可）"filesystem": {// 【服务名称】"filesystem"——你给这个服务起的名字，WorkBuddy 用它来标识和调用"command": "npx",// 【启动命令】告诉 WorkBuddy 用什么程序来启动这个 MCP 服务// "npx" 是 Node.js 自带的包执行器，无需提前全局安装，运行时自动拉取"args": [// 【命令参数】传递给 npx 的参数数组，按顺序拼接成完整命令// 最终等价于在终端执行：npx -y @modelcontextprotocol/server-filesystem /Users/.../Desktop /Users/.../Documents"-y",// 【自动确认】-y 表示 --yes，跳过 npx 的"是否安装"确认提示，确保无人值守启动"@modelcontextprotocol/server-filesystem",// 【MCP 包名】这是 Anthropic 官方维护的文件系统 MCP Server// 它提供了读取目录、读文件、写文件等工具能力"/Users/你的用户名/Desktop",// 【授权路径1】允许 WorkBuddy 访问的目录路径（绝对路径）// 只开放必要的目录，不要放整个 home 目录"/Users/你的用户名/Documents"// 【授权路径2】可以同时授权多个目录}

Windows 用户路径写法：C:\\Users\\你的用户名\\Desktop。

第三步：重启 WorkBuddy，验证

改完配置后重启 WorkBuddy。然后在对话框里试一句：

帮我看看桌面上有哪些文件

如果 WorkBuddy 能列出桌面文件，说明 MCP 通了。

四、实战二：连接数据库

让 WorkBuddy 直接查数据库。以 PostgreSQL 为例：

{// 【顶层】MCP 配置文件根对象"mcpServers": {// 【服务名称】"postgres"——自定义名称，标识这个数据库连接"postgres": {"command": "npx",// 【启动命令】用 npx 启动 MCP Server"args": [// 【命令参数】"-y",// 【自动确认】跳过安装确认提示"@modelcontextprotocol/server-postgres"// 【MCP 包名】PostgreSQL 数据库 MCP Server，提供 SQL 查询、表结构读取等工具],"env": {// 【环境变量区】通过环境变量传递敏感信息（密钥、连接串等），不硬编码在 args 里// 环境变量的值不会暴露在进程列表（ps）中，比写在命令行参数里更安全"DATABASE_URL": "postgresql://用户名:密码@localhost:5432/数据库名"// 【数据库连接串】标准 PostgreSQL 连接格式// 格式：postgresql://用户名:密码@主机地址:端口号/数据库名}

配置好后，直接用自然语言查数据：

查一下上个月销售额最高的10个产品，按金额降序排列

WorkBuddy 会自动生成 SQL、连接数据库、执行查询、返回结果。你不需要写一行 SQL。

如果是 SQLite 数据库，配置更简单：

{"mcpServers": {"sqlite": {"command": "npx","args": ["-y",// 【自动确认】"@modelcontextprotocol/server-sqlite",// 【MCP 包名】SQLite 数据库 MCP Server"--db-path",// 【数据库路径参数】指定 SQLite 数据库文件的路径"/Users/你的用户名/项目/data/mydb.sqlite"// 【数据库文件路径】你的 .sqlite 文件的绝对路径}

多个服务可以写进同一个 mcp.json，WorkBuddy 会根据你的需求自动选择调用哪个：

{// 【顶层】MCP 配置根对象"mcpServers": {// 【服务1】文件系统 MCP——读写本地文件"filesystem": {"command": "npx","args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]// npx -y @modelcontextprotocol/server-filesystem /workspace},// 【服务2】PostgreSQL MCP——查询数据库"postgres": {"command": "npx","args": ["-y", "@modelcontextprotocol/server-postgres"],// npx -y @modelcontextprotocol/server-postgres"env": {"DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"// 【环境变量】数据库连接串，不暴露在命令行中},// 【服务3】Playwright MCP——浏览器自动化"playwright": {"command": "npx","args": ["@playwright/mcp@latest"]// npx @playwright/mcp@latest// @latest 表示使用最新版本}

这个配置让 WorkBuddy 同时拥有了文件读写、数据库查询、浏览器自动化三种能力。

六、自建 MCP Server：以 Python 为例

现成的 MCP Server 覆盖了常见场景。但如果你的需求很特殊——比如连接公司内部的 ERP 系统、调用私有 API——就需要自己写一个。

用 Python 写一个 MCP Server 非常简单。以"查询天气"为例：

第一步：安装依赖

# 安装 Python 的 MCP SDK，提供 MPCServer 类和 @server.tool() 装饰器等核心能力pip install mcp

第二步：写服务代码

# ========== 天气查询 MCP Server 完整示例 ==========# 【导入 MCP 框架】MPCServer 是创建 MCP 服务的核心类from mcp import MPCServer# 【导入 HTTP 请求库】用于调用外部天气 APIimport requests# 【创建服务实例】参数 "weather-server" 是这个 MCP 服务的唯一标识名称# 这个名字会出现在 WorkBuddy 的工具列表中，建议用有意义的命名server = MPCServer("weather-server")# 【注册工具】@server.tool() 装饰器将一个普通函数注册为 MCP 工具# WorkBuddy 会自动发现这个工具，并在需要时调用它@server.tool()def get_weather(city: str) -> str:# ↑ 函数名 "get_weather" 会作为工具名暴露给 AI# ↑ 参数 city: str —— 类型注解定义了工具的输入参数，AI 会根据它生成调用参数# ↑ 返回值 -> str —— 工具执行后返回给 AI 的结果类型"""查询指定城市的天气信息。参数 city 为城市名称，如'北京'。"""# ↑ 文档字符串（docstring）会被 MCP 协议读取，作为工具描述发送给 AI# ↑ AI 看到这段描述后，就知道什么时候该调用这个工具、传什么参数# 【调用外部 API】构造请求 URL，{city} 会被替换为实际传入的城市名# 这里以示例 API 演示，实际使用时替换为你的真实 API 地址response = requests.get(f"https://api.weather.com/{city}")# 【返回结果】return 的内容会作为工具执行结果返回给 WorkBuddy# AI 会基于这个返回值生成最终回复给用户return response.text# 【程序入口】当 Python 直接运行这个文件时（而非被 import 时），启动 MCP 服务if __name__ == "__main__":# 【启动服务】server.run() 启动 MCP 服务，开始监听来自 WorkBuddy 的调用请求# 默认使用 stdio（标准输入输出）传输方式，与 WorkBuddy 通信server.run()

第三步：在 mcp.json 中注册

{// 【顶层】MCP 配置根对象"mcpServers": {// 【注册自建服务】key 名称 "weather" 自定义，保持唯一即可"weather": {"command": "python",// 【启动命令】用 python 解释器运行我们的服务脚本"args": ["/path/to/weather_server.py"]// 【脚本路径】你写的 weather_server.py 文件的绝对路径}

重启 WorkBuddy 后，你就可以说"帮我查一下北京今天的天气"，它会自动调用你写的服务。

七、常见的三个问题问题1：JSON 格式错误

这是最常见的翻车点。多一个逗号、少一个引号，MCP 就加载失败。

现象：配置完重启，MCP 服务没加载，工具列表为空。

解决：用 python -m json.tool mcp.json 验证 JSON 格式。如果报错，说明格式有问题。最常见的错误是最后一个 key-value 后面多了逗号。

问题2：Node.js 版本太低

现象：MCP Server 启动时报 The engine "node" is incompatible。

解决：升级到 Node.js 20+。用 nvm 管理版本最方便：

# 安装 Node.js 20 版本nvm install 20# 切换到 Node.js 20 版本（当前终端会话生效）nvm use 20

现象：MCP Server 启动失败，报 spawn npx ENOENT。

原因：WorkBuddy 启动 MCP 子进程时，PATH 环境变量可能和你的终端不同。

解决：在 mcp.json 里把 command 写成 npx 的绝对路径：

{// 【修复方式】用绝对路径替代 "npx""command": "/opt/homebrew/bin/npx",// ↑ macOS Homebrew 安装的 Node.js 中 npx 的典型路径// Linux 常见路径：/usr/local/bin/npx 或 /usr/bin/npx// Windows 常见路径：C:\\Users\\用户名\\AppData\\Roaming\\npm\\npx.cmd"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]}

用 which npx 找到你机器上的实际路径。

八、安全提醒

MCP Server 跑在本地，拥有你配置的权限。几个原则：

1. 最小权限：文件系统 MCP 只开放必要的目录，不要把整个 home 目录丢进去。
2. 密钥用环境变量：API Key 不要硬编码在 mcp.json 里，用 env 字段。
3. 数据库用只读账号：给 MCP 配的数据库账号，权限设为只读，避免误操作。

类别

MCP Server

能力

文件系统

server-filesystem

读写指定目录

数据库

server-sqlite/

server-postgres

自然语言查数据库

浏览器

@playwright/mcp

网页自动化、截图

GitHub

server-github

查看/提交代码、管理 Issue

Notion

server-notion

读写 Notion 文档

搜索

server-brave-search

网页搜索

这些都在 awesome-mcp-servers 仓库里能找到，9 万多 star，基本覆盖了所有常见的外部服务。

十、总结

1. MCP 是 WorkBuddy 的"USB 接口"：插上什么服务，就多了什么能力。
2. 配置只需一个 JSON 文件：mcp.json 里写好服务名称、启动命令、环境变量。
3. 自建 MCP Server 用 Python 很简单：定义一个工具函数，几行代码就能让 AI 调用你的私有 API。
4. 安全第一：最小权限、密钥用环境变量、数据库用只读账号。

MCP 把 WorkBuddy 从"本地工具"升级为"系统连接器"。你的数据库、API、企业系统，全都可以通过 MCP 接入 AI 的工作流。这是从"用工具"到"建系统"的关键一步。