AI 教程 · 2026年10月16日 - AI实战指南

无涯2026-10-162026-10-16

2026-10-16 AI教程：给 AI 装上「手」——从零构建你的第一个 MCP Server

背景

2026 年的今天，大模型早就不是「聊天机器」了。从阶跃 STEPX Neo 手机里系统级的 Tool Call，到 DeepSeek Harness 的「一切皆插件」，再到 Claude Code 帮你改代码——Agent 能不能干活，取决于它能不能调用工具。

但工具怎么接？每个模型厂商一套 SDK、每家应用一套插件规范的时代已经过去了。2024 年底 Anthropic 提出的 MCP（Model Context Protocol，模型上下文协议），如今已成为 Agent 接入工具的事实标准：它给「AI 连接外部世界」定了一个统一接口，被形象地称为 「AI 世界的 USB-C」。

本教程带你：

理解 MCP 的核心架构（Host / Client / Server、Tools / Resources / Prompts）；
用一条命令跑起一个现成的 MCP Server；
用 Python 从零写一个自己的 MCP Server，并接入 Claude Code 和 Cursor；
掌握排错与安全要点。

全程无需 GPU，只需一台装了 Python 的电脑。

准备环境

软件要求

**Python 3.10+**（检查：python3 --version）
**Node.js 18+**（可选，跑官方示例 Server 用；检查：node -v）
uv（可选但推荐，Python 包管理更快）：curl -LsSf https://astral.sh/uv/install.sh | sh
一个支持 MCP 的客户端：Claude Code（npm install -g @anthropic-ai/claude-code）或 Cursor

核心概念先花 3 分钟

MCP 是客户端-服务器架构，四个角色：

角色	作用	类比
Host	用户面对的应用程序（Claude Code、Cursor、Claude Desktop）	你的电脑
Client	Host 内部与 Server 通信的组件，每个 Server 一个 Client	USB 接口
Server	提供工具、资源、提示词的程序（可以本地跑，也可以远程）	U 盘/外设
Transport	通信方式：stdio（本地进程）或 Streamable HTTP（远程）	数据线

Server 能提供三类能力：

Tools：可执行的函数（查天气、读写文件、调 API）—— Agent 的「手」；
Resources：只读数据（文档、数据库记录）—— Agent 的「资料库」；
Prompts：可复用的提示词模板—— Agent 的「操作手册」。

本教程聚焦最常用的 Tools。

操作步骤

1. 先跑一个现成的 MCP Server（官方示例）

不用写代码，先感受一下「工具长什么样」。用 npx 启动官方文件系统 Server：

1	npx -y @modelcontextprotocol/server-filesystem /tmp

它会启动一个通过 stdio 通信的进程，把 /tmp 目录暴露给 AI。现在它是「空转」的——没有 Host 连它。我们马上接入。

玩一下更全能的 server-everything：npx -y @modelcontextprotocol/server-everything，它演示了 Tools、Resources、Prompts 三类能力的完整写法，是绝佳的参考代码。

2. 用 FastMCP 写自己的第一个 Server

FastMCP 是官方推荐的 Python 框架，几行就能定义一个工具。安装：

1
2
3

pip install "mcp[cli]"
# 或者用 uv：
uv add "mcp[cli]"

新建 time_server.py：

from mcp.server.fastmcp import FastMCP
import datetime

# 创建 Server，名字会显示在客户端里
mcp = FastMCP("TimeServer")


# 用装饰器把一个普通函数变成 AI 可调用的 Tool
@mcp.tool()
def current_time(timezone: str = "UTC") -> str:
    """返回指定时区的当前时间。timezone 示例：Asia/Shanghai、UTC、America/New_York。"""
    from zoneinfo import ZoneInfo
    try:
        now = datetime.datetime.now(ZoneInfo(timezone))
        return f"{timezone} 当前时间: {now:%Y-%m-%d %H:%M:%S}"
    except Exception as e:
        return f"无法解析时区 {timezone}: {e}"


@mcp.tool()
def add(a: float, b: float) -> float:
    """计算两个数字之和。"""
    return a + b


if __name__ == "__main__":
    mcp.run()  # 默认走 stdio 传输

注意三个要点：

函数名即工具名，所以用清晰的小写蛇形命名；
docstring 就是给 AI 看的说明书，写得越具体（参数含义、示例值），模型调用越准——这是 MCP 开发里最重要的习惯；
类型注解驱动参数 schema，timezone: str 会被自动转成 JSON Schema 让模型知道该传什么。

3. 本地测试：先不接客户端，用 MCP Inspector

直接跑 python time_server.py 只会看到进程挂着，因为 stdio 模式等着客户端来连。用官方调试工具验证：

1	npx -y @modelcontextprotocol/inspector python time_server.py

浏览器打开 http://localhost:6274：

左侧能看到 Server 暴露的工具列表（current_time、add）；
点进工具可以填参数、手动调用，看返回结果；
这比「直接塞给 AI 然后猜」高效得多——先确保工具本身是对的。

4. 接入 Claude Code

Claude Code 支持一条命令注册本地 MCP Server：

1	claude mcp add time-server -- python /path/to/time_server.py

查看注册情况：

1	claude mcp list

然后在 Claude Code 里直接问：

1	现在上海几点了？用 time-server 查一下

你会看到模型先「调用工具」再回答——它自己完成了参数解析（Asia/Shanghai）和调用。如果报错，先 claude mcp remove time-server 再重新 add。

5. 接入 Cursor

Cursor 用项目级配置文件。在项目根目录建 .cursor/mcp.json：

{
  "mcpServers": {
    "time-server": {
      "command": "python",
      "args": ["/path/to/time_server.py"]
    }
  }
}

保存后在 Cursor 里：Settings → MCP 应该能看到 time-server 及其工具。如果没生效，点右上角刷新，或重启 Cursor。之后在对话里输入 /mcp 可以查看、开关工具。

其他支持 MCP 的客户端（Claude Desktop、Windsurf、VS Code Copilot 等）配置思路完全一样：settings.json 或 GUI 里指向 command + args 即可。

6. 进阶：给工具加「状态」和「资源」

工具不一定要无状态。举个实用的例子——给 Server 加一个「记事本」工具，让 AI 能记住跨对话的信息：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("NoteServer")
notes = {}  # 内存存储，重启即失；生产环境换成数据库/文件


@mcp.tool()
def save_note(key: str, content: str) -> str:
    """保存一条笔记，key 是笔记名，content 是内容。"""
    notes[key] = content
    return f"已保存笔记 {key}"


@mcp.tool()
def get_note(key: str) -> str:
    """读取指定笔记的内容；不存在时明确告知。"""
    return notes.get(key, f"没有找到笔记 {key}")


if __name__ == "__main__":
    mcp.run()

再注册一个资源，让 AI 对话时自动带上背景信息：

@mcp.resource("config://app")
def get_config() -> str:
    """应用配置，AI 回答问题时自动可见。"""
    return "应用名: DemoApp; 版本: 1.0; 支持语言: 中文/English"

用 Inspector 或客户端刷新后，你会看到多了一个 Resource——模型在相关对话中会自动读取它，无需显式调用。

7. 排错速查表

症状	大概率原因	处理
客户端显示 Server 连接失败	路径不对 / 依赖没装	先在终端手动跑一遍 `python time_server.py`，确认能启动
工具调用了但报错	docstring 与实现不符	用 Inspector 手动测工具，修完再给客户端
参数总传错	类型注解不明确	给参数写默认值、写死示例（`timezone: str = "UTC"`）
stdio 模式进程一闪而过	启动即崩溃	看 stderr：`python time_server.py 2>&1`
模型「假装」调用但没实际效果	Server 无状态或写错位置	检查工具是否真的执行（加 print 看日志）

8. 安全红线（重要）

MCP Server 的权力 = 你给它的权限。官方 server-filesystem 你让它暴露 /tmp，它就只能碰 /tmp；你自己写的工具能执行命令，就真的能执行命令。三条铁律：

最小权限：只暴露必要的目录/能力，别图省事给 os.system 裸奔；
注意 Prompt 注入：工具返回的网页/文件内容里可能藏指令，别让外部内容操纵你的 Agent（Anthropic 2021 年就在内部文档里讨论「如何安全部署执行代码的 Tool」——今天这个问题依然是头号风险）；
远程 Server 要鉴权：用 Streamable HTTP 部署远程 Server 时，务必加 API Key / OAuth，否则你的工具等于公网裸奔。