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

萧青山

64人浏览 · 2026-07-04 12:00:00

萧青山 · 2026-07-04 12:00:00 发布

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)`解码后再使用