MCP协议实战：用Python 5分钟搭建你的第一个MCP Server（附完整代码）

导读：MCP协议（Model Context Protocol）已经成为AI Agent调用外部工具的事实标准。阿里、腾讯、Google全面支持，魔搭MCP广场上线近1500个Server——但全网实操教程依然稀缺。本文用一段可直接运行的Python代码，带你从零搭建第一个MCP Server，解决"Agent想操作数据库/查天气/发邮件，却不知道如何标准化接入"的痛点。适合有Python基础的开发者阅读，附完整报错排查指南。

一、为什么MCP协议突然火了

2024年11月，Anthropic发布了MCP协议，初衷很简单：让AI Agent连接外部工具时，不再需要为每个工具写一套定制化的胶水代码。

想象一个场景：你的Agent需要查天气、操作数据库、调用GitHub API。以前的做法是——每个API写一段适配代码，格式五花八门，维护成本高得离谱。MCP协议做的就是统一这件事：工具提供方按标准写一个MCP Server，任何支持MCP的Agent（Claude、GPT、DeepSeek等）都能直接调用，就像USB接口插上去就能用。

2026年，MCP已经成了行业共识：

• Anthropic将MCP捐赠给Linux Foundation
• 魔搭MCP广场上线近1500个Server，覆盖搜索、地图、支付等领域
• 中国银联通过MCP协议对接加油、充电、停车等支付场景

对开发者来说，掌握MCP Server开发已经是AI Agent落地的必备技能。

二、MCP协议核心概念（3分钟搞懂）

在开始写代码之前，先理清三个核心概念：

• MCP Server：工具提供方，暴露一组标准化的工具（Tools）、资源（Resources）和提示词（Prompts）。
• MCP Client：Agent端，负责发现Server、调用工具、处理返回结果。
• Transport：通信方式，支持stdio（本地进程）和SSE（HTTP流），生产环境常用SSE。

MCP协议本质上定义了一套JSON-RPC 2.0的通信规范。开发者不需要关心底层协议细节，因为官方SDK已经帮我们封装好了。

三、环境准备

开始之前，确保你的环境满足以下要求：

依赖项	版本要求	说明
Python	>= 3.10	MCP SDK需要3.10+
pip	最新版	用于安装依赖

安装MCP Python SDK：

pip install mcp

验证安装：

pip show mcp

如果输出了包信息（Name、Version等），说明环境准备就绪。

注意：mcp 模块没有直接暴露 __version__ 属性，因此 python -c "import mcp; print(mcp.__version__)" 会报 AttributeError。使用 pip show mcp 是更可靠的验证方式。

四、5分钟搭建你的第一个MCP Server

下面这段代码是一个完整的、可运行的MCP Server示例。它暴露了三个工具：计算器、字符串反转、当前时间查询。

4.1 编写Server代码

创建文件 my_first_mcp_server.py：

from mcp.server.fastmcp import FastMCP
import datetime

# 初始化MCP Server，指定名称
mcp = FastMCP("demo-server")


# 工具1：加法计算器
@mcp.tool()
def add(a: float, b: float) -> float:
    """计算两个数的和。"""
    return a + b


# 工具2：字符串反转
@mcp.tool()
def reverse_string(text: str) -> str:
    """将输入字符串反转。"""
    return text[::-1]


# 工具3：获取当前时间
@mcp.tool()
def get_current_time() -> str:
    """返回当前系统时间（ISO格式）。"""
    return datetime.datetime.now().isoformat()


# 启动Server（stdio模式，适合本地测试）
if __name__ == "__main__":
    mcp.run(transport="stdio")

代码解析：

• FastMCP("demo-server")：创建一个MCP Server实例，名称会显示在Client的工具列表里。
• @mcp.tool()：装饰器将普通Python函数注册为MCP协议工具，函数名就是工具名，docstring会被Client读取作为工具描述。
• mcp.run(transport="stdio")：启动Server，使用stdio模式（通过标准输入输出通信，适合本地调试）。

4.2 用Client调用验证

创建文件 test_client.py：

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio


async def main():
    # 配置Server启动参数
    server_params = StdioServerParameters(
        command="python",
        args=["my_first_mcp_server.py"],
    )

    # 建立stdio连接
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # 初始化会话
            await session.initialize()

            # 列出所有可用工具
            tools = await session.list_tools()
            print("=== 可用工具列表 ===")
            for tool in tools.tools:
                print(f"  - {tool.name}: {tool.description}")

            # 调用add工具
            result = await session.call_tool("add", {"a": 3, "b": 5})
            print(f"\n=== add(3, 5) = {result} ===")

            # 调用reverse_string工具
            result = await session.call_tool(
                "reverse_string", {"text": "MCP协议"}
            )
            print(f"=== reverse_string('MCP协议') = {result} ===")

            # 调用get_current_time工具
            result = await session.call_tool("get_current_time", {})
            print(f"=== 当前时间 = {result} ===")


if __name__ == "__main__":
    asyncio.run(main())

运行测试：

python test_client.py

预期输出：

=== 可用工具列表 ===
  - add: 计算两个数的和。
  - reverse_string: 将输入字符串反转。
  - get_current_time: 返回当前系统时间（ISO格式）。

=== add(3, 5) = 8.0 ===
=== reverse_string('MCP协议') = 议协PCM ===
=== 当前时间 = 2026-07-04T09:15:32.123456 ===

如果看到了上面的输出，恭喜你——你的第一个MCP Server已经跑通了。

4.3 进阶：暴露资源（Resource）

除了工具，MCP协议还支持暴露资源。资源是只读的数据，适合返回配置信息、文档内容等。

在 my_first_mcp_server.py 中追加：

import urllib.parse

# 暴露一个静态资源：Server说明文档
@mcp.resource("docs://about")
def get_about() -> str:
    """返回Server的基本信息。"""
    return "这是一个演示用的MCP Server，用于学习MCP协议开发。"


# 暴露一个动态资源：带参数
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """根据名字返回问候语。"""
    decoded_name = urllib.parse.unquote(name)
    return f"你好，{decoded_name}！欢迎学习MCP Server开发。"

资源URI采用 scheme://path 格式，Client可以通过 session.read_resource() 方法读取。

踩坑提醒：MCP框架会对Resource路径参数进行URL编码，因此如果参数包含中文或特殊字符，在Server端需要用 urllib.parse.unquote() 解码，否则会得到 %E5%BC%A0%E4%B8%89 这样的编码字符串而非"张三"。

五、常见问题与报错排查

在MCP Server开发过程中，这几个坑我踩过，帮你提前规避：

报错信息 / 问题现象	原因	解决方案
ModuleNotFoundError: No module named 'mcp'	MCP SDK未安装或安装在错误环境	确认pip install mcp执行成功，且Python解释器路径一致
AttributeError: module 'mcp' has no attribute '__version__'	mcp包未暴露__version__属性	改用pip show mcp查看版本号，或直接import mcp验证安装
ConnectionClosedError: stdio connection closed	Server进程崩溃或未启动	检查Server代码是否有语法错误，单独运行python my_first_mcp_server.py验证
Tool not found: xxx	工具名拼写错误或Server未注册	确认@mcp.tool()装饰器已加，且调用时工具名完全一致
TimeoutError	Client等待Server响应超时	检查Server是否有死循环或阻塞操作，异步函数要正确await
TypeError: missing required argument	调用工具时参数缺失或类型不匹配	对照函数签名检查参数名和类型，注意int和float的区别
Resource路径参数中文乱码（显示为%E5%BC%A0%E4%B8%89）	MCP框架对Resource路径参数自动做了URL编码	在Server端用urllib.parse.unquote(name)解码后再使用

额外建议：

• 生产环境不要用stdio模式，改用SSE（Server-Sent Events）通过HTTP通信，便于分布式部署。
• 工具函数的docstring一定要写清楚，这直接影响AI Agent理解工具用途的准确性。
• 如果工具执行耗时较长，建议在docstring中标注，让Agent知道可能需要等待。

六、从Demo到生产：下一步怎么走

跑通上面的代码只是第一步。在实际项目中，MCP Server通常会对接真实的外部服务。几个典型的扩展方向：

• 数据库MCP Server：暴露SQL查询工具，让Agent能查业务数据。
• 文件系统MCP Server：暴露文件读写工具，让Agent能操作本地文件。
• 第三方API MCP Server：把公司内部API封装成MCP工具，让Agent调用。

此外，MCP协议支持三种通信模式，本文用的是最简单的stdio模式。但当你要把MCP Server部署到生产环境时，stdio模式显然不够用——你需要了解SSE（Server-Sent Events）和HTTP Stream模式，才能做出正确的架构选型。

我在下一篇文章中会深度对比三种模式：

• stdio：本地进程通信，适合开发和测试
• SSE：基于HTTP的单向流，适合浏览器场景
• HTTP Stream：双向流式传输，适合高并发生产环境

[推荐阅读：MCP协议的三种服务模式深度解析：stdio、SSE、HTTP Stream怎么选？]（发布后将更新链接）

跑通上面的代码只是第一步。在实际项目中，MCP Server通常会对接真实的外部服务。几个典型的扩展方向：

• 数据库MCP Server：暴露SQL查询工具，让Agent能查业务数据。
• 文件系统MCP Server：暴露文件读写工具，让Agent能操作本地文件。
• 第三方API MCP Server：把公司内部API封装成MCP工具，让Agent调用。

我在后续文章中会逐一拆解这些实战案例，包括MySQL/PostgreSQL接入、文件系统权限控制、以及多MCP Server组合使用的架构设计。

七、总结

本文从一个实际问题出发——AI Agent如何标准化调用外部工具——引出了MCP协议的背景和核心价值。通过一段可直接运行的Python代码，我们完成了：

• 安装MCP协议Python SDK
• 用FastMCP快速搭建MCP Server
• 注册工具（Tool）和资源（Resource）
• 用Client连接并调用验证
• 排查了5个最常见的报错

MCP协议正在重塑AI Agent与外部世界的连接方式。2026年，掌握MCP Server开发的开发者，将在智能体应用落地的浪潮中占据先机。

---

相关阅读：

• OpenSPG启动报错"Access denied for user ‘root’"？一文彻底解决
• 智能体"互联互通"的国家标准发布：AI助手终于能互相聊天了
• GB/Z 185《人工智能 智能体互联》系列标准核心内容梳理

---

你在搭建MCP Server时遇到了什么问题？或者你打算用MCP对接什么类型的工具（数据库、API、文件系统）？ 欢迎在评论区交流，我会整理成合集持续更新，有价值的提问我会单独出一篇深度分析。

如果这篇文章对你有帮助，欢迎 点赞 + 收藏。收藏率决定算法推荐权重，你的每一次收藏都能让更多开发者看到这篇实战指南。