朝花夕拾
关于RSS 订阅
教程·阅读约 3 分钟·
MCP 协议入门实战：为 AI 助手搭建自定义工具扩展

MCP 协议入门实战：为 AI 助手搭建自定义工具扩展

模型上下文协议（MCP）正在成为 AI 助手工具扩展的标准接口，从零配置一个文件系统服务器到 GitHub 集成，十分钟上手

四
四月·

原创。从零配置一个 MCP 服务器，让 AI 助手获得操作文件系统、查询数据库、管理 GitHub 仓库等实际能力

2025 年底，Anthropic 开源了模型上下文协议（Model Context Protocol，简称 MCP）。在此之前，每个 AI 助手都有自己的一套工具接入方式——Claude 用插件、OpenAI 用 Function Calling、各种开源项目各玩各的。MCP 想要做的事情很简单：给 AI 助手定义一个通用的「USB 接口」，让任何工具都能即插即用。

这个想法在 2026 年的今天已经开始兑现。MCP 的生态飞速增长，从文件系统到数据库，从 GitHub 到 Figma，几百个官方和社区服务器已经可用。这篇文章带你从零开始，搭建一个可用的 MCP 环境。

MCP 到底是什么

拆开来看，MCP 定义了三方角色：

主机（Host）：运行 AI 助手的程序，比如 Claude Desktop、各种 IDE 插件、或者 Hermes Agent 这样的终端工具。主机负责管理 MCP 连接，把工具暴露给 LLM。

客户端（Client）：主机内部与 MCP 服务器建立一对一连接的部分。一个主机可以同时连接多个服务器。

服务器（Server）：暴露特定工具的程序。比如文件系统服务器暴露了读文件、写文件、列目录等工具；GitHub 服务器暴露了创建 Issue、创建 PR 等工具。

通信过程是标准化的：主机启动服务器子进程（或者连接远程服务器的 HTTP 端点），通过 JSON-RPC 协议交换消息。服务器告诉主机「我有这些工具」，主机把它们注册为 AI 助手可调用的函数。当 AI 决定调用某个工具时，主机把请求转发给服务器，服务器执行操作并返回结果。

—— 广告 ——

准备工作

你需要以下环境：

code
# 安装 Node.js（用于 npx 运行的 MCP 服务器）
# 确认版本
node --version   # 需要 v18+
npm --version
 
# 安装 uv（用于 Python 生态的 MCP 服务器）
curl -LsSf https://astral.sh/uv/install.sh | sh
uv --version
 
# 安装 MCP Python SDK（某些客户端需要）
pip install mcp

大多数 MCP 服务器通过 npx（Node 包执行器）或 uvx（Python 包执行器）一行命令启动，不需要单独安装。

第一个 MCP 服务器：获取当前时间

从一个最简单的例子开始。配置一个返回当前时间的 MCP 服务器：

code
# 这是配置示例，不同客户端配置位置不同
mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

uvx mcp-server-time 一行命令就启动了一个标准 MCP 服务器，暴露 get_current_time 和 get_timezone_list 两个工具。配置好后重启你的 AI 助手，问一句"现在几点了"——它就会调用这个工具返回精确时间，而不是凭训练数据猜测。

进阶：文件系统服务器

最有实用价值的入门服务器之一。它让 AI 助手可以直接读写你指定的目录：

code
mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    timeout: 30

配置完成后，AI 助手就能读取、写入、编辑这个目录下的文件了。这在代码开发场景中非常有用——你可以让 AI 直接创建文件、修改代码、搜索内容，而不需要手动开一个终端。

注意 -y 参数：npx 需要这个标志来跳过安装确认。而 timeout: 30 设置了单次工具调用的超时时间，大文件读写可能需要更长等待时间。

实用：GitHub 集成

对于开发者来说，GitHub 服务器是最常用的 MCP 服务器之一：

code
mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "你的_GitHub_Token"
    timeout: 60

配置后，AI 助手可以直接创建 Issue、搜索代码、查看 PR 状态、甚至创建 Pull Request。不再需要在 AI 对话和 GitHub 页面之间来回切换。

GitHub Token 需要从 GitHub Settings → Developer settings → Personal access tokens 生成，至少需要 repo 和 issues 权限。

架构深入：Stdio vs HTTP 传输

MCP 支持两种传输方式，用途不同：

Stdio 传输（最常见）：主机把 MCP 服务器作为子进程启动，通过标准输入输出通信。适用于本地运行的服务器，启动快、无需网络、安全性好（子进程继承的路径和控制权在主机手里）。

code
mcp_servers:
  my_server:
    command: "npx"
    args: ["-y", "some-mcp-server"]

HTTP 传输：连接远程运行的 MCP 服务器，通过 HTTP 或 SSE 通信。适用于共享服务、企业内部 API、或者不想在本地装运行时的场景。

code
mcp_servers:
  company_api:
    url: "https://mcp.internal.company.com/v1"
    headers:
      Authorization: "Bearer sk-your-token"

安全性：环境变量过滤

这是 MCP 设计中容易被忽略但很重要的一点。当你通过 Stdio 启动 MCP 服务器时，它默认只继承最基础的几个环境变量——PATH、HOME、USER、LANG 等。

你的 API Key、Token、密钥不会被自动传递给 MCP 子进程，除非你明确在配置中指定：

code
mcp_servers:
  my_server:
    command: "npx"
    args: ["-y", "some-server"]
    env:
      # 只有这里显式列出的变量才会传给子进程
      API_KEY: "sk-xxxx"

这防止了不可信的 MCP 服务器窃取你的环境变量。安全性设计值得注意。

多服务器并行

MCP 的一个关键优势是可以同时接入多个服务器，每个服务器的工具自动以不同前缀区分：

code
mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]
 
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
 
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxx"
 
  sqlite:
    command: "uvx"
    args: ["mcp-server-sqlite", "--db-path", "/home/user/data.db"]

配置好之后，一个 AI 助手可以同时拥有查时间、读写文件、管理 GitHub、查询数据库四种能力。每种能力来自不同的服务器，但都通过同一个 MCP 协议接入。

常见问题

启动失败：command not found。最常见的原因是 npx 或 uvx 不在 PATH 中。检查 which npx 和 which uvx 是否返回有效路径。

超时断开。MCP 服务器连接是持久化的，但有些服务器启动比较慢。如果看到超时日志，增加 connect_timeout 值（默认 60 秒）：

code
mcp_servers:
  slow_server:
    command: "npx"
    args: ["-y", "some-heavy-server"]
    connect_timeout: 120

工具没出现。确认配置文件的 YAML 缩进正确——这是最常见的错误。MCP 配置通常在 mcp_servers 键下，缩进两格，服务器名称缩进四格。

HTTP 服务器报 ImportError。如果你使用 HTTP 传输但 MCP Python SDK 版本太旧，可能不支持 HTTP 客户端。升级：pip install --upgrade mcp。

MCP 的意义

MCP 不是一个「另一个工具框架」。它是一个标准化接口，就像 USB-C 对于外设的意义。在 MCP 之前，每个 AI 助手的工具扩展机制都是私有的、互不兼容的。一个为 Claude Desktop 写的插件不能在 Cursor 里用，一个为 OpenAI 写的 Function Calling 不能移植到 Ollama。

MCP 改变了这一点。协议是开放的，实现是轻量的，生态是共享的。一个 MCP 服务器写好了，理论上任何支持 MCP 的主机都可以直接使用。对于开发者来说，这意味着工具生态的可复用性——你写一次集成，所有 AI 助手都能用。

截至 2026 年中，MCP 的官方和社区服务器已经覆盖了文件系统、数据库、版本控制、云服务、设计工具、浏览器自动化、搜索等多个领域。如果你有一个常用的工具或服务，很可能已经有人为它写了 MCP 服务器。

如果还没有——那可能就是你来写了。MCP 服务器的开发接口非常简单，用 Python 或 TypeScript 几十行代码就能实现一个基本的服务器。这又是一个话题了。

MCPAI工具AI编程开发工具LLM协议入门教程
分享到
微博Twitter

© 2026 四月 · CC BY-NC-SA 4.0

原文链接：https://www.aprilzz.com/tutorials/mcp-intro-guide

相关文章

AI 辅助测试实战：用 LLM 构建自动化测试工作流

从自动生成单元测试到持续维护测试套件，一套用 LLM 做测试的完整工作流——不依赖特定工具，只讲通用方法论和实战操作。

AI 编码代理的提示词工程实战指南

系统提示、任务描述、上下文管理——让 AI 编码代理产出高质量代码的提示词技巧，涵盖五种实战模式和大量可复用的提示模板。

AI 代码审查自动化：如何让 AI 代理帮你把关代码质量

从搭建审查流程到配置自动化检查规则和编写审查提示语，手把手教会你用 AI 代理建立一套持续运行的代码审查系统