1. MCP 是什么？ #

• MCP 让应用以标准协议向大模型（LLM）提供上下文与能力（数据即 Resources、动作即 Tools、交互模板即 Prompts）。
• 本 SDK 提供：
  • 服务器端：高层 FastMCP（装饰器快速开发）与低层 Server（完全可控）
  • 客户端：ClientSession 通过多种传输（stdio / Streamable HTTP / SSE）与 MCP 服务器对话
  • CLI 工具：mcp 命令助你开发、调试和集成

2. Windows 环境准备 #

• 操作系统：Windows 10 或更高版本
• Python：3.10+（建议 3.12/3.13）
• 可选工具：uv（推荐），用于快速运行与依赖管理

2.1 检查 Python #

在命令提示符（cmd.exe）中执行：

python --version

若未安装或版本过低，请先安装新版 Python，并勾选 “Add python.exe to PATH”。

2.2 安装 uv（可选但强烈推荐） #

• 若系统已有 pipx：

  pipx install uv

• 或使用 pip：

  python -m pip install --upgrade uv

  验证：

  uv --version

3. 安装 MCP SDK（两种方式） #

你可以在任意工作目录中创建一个临时目录（示例：C:\mcp-project）。

3.1 使用 uv（推荐） #

cd C:\mcp-project
uv init
uv add "mcp[cli]"

3.2 使用 pip #

cd C:\mcp-project
python -m venv .venv
call .venv\Scripts\activate
python -m pip install --upgrade pip
pip install "mcp[cli]"

验证安装：

mcp --help

看到命令帮助即表示 CLI 安装成功。

4. 示例代码 #

• 启动一个最简单的 FastMCP 服务器（stdio 传输）
• 启动一个 MCP 客户端，通过 stdio 与该服务器建立会话
• 初始化后列出服务器的工具、资源与 prompts

请新建文件 check_mcp_setup.py

# 导入异步编程模块
import asyncio

# 从 mcp SDK 导入客户端会话、stdio 服务器参数、类型定义
from mcp import ClientSession, StdioServerParameters, types

# 导入 stdio 客户端适配器
from mcp.client.stdio import stdio_client

# 导入 FastMCP 服务器实现
from mcp.server.fastmcp import FastMCP

# 创建一个名为 "Hello-MCP" 的 FastMCP 服务器实例
mcp = FastMCP(name="Hello-MCP")


# 注册一个名为 hello 的工具，返回固定问候语
@mcp.tool()
def hello() -> str:
    # 返回一段问候语
    return "Hello from MCP server!"


# 注册一个资源，URI 为 mcp://info，返回服务器基本信息
@mcp.resource("mcp://info")
async def get_info():
    # 返回服务器的名称、版本和描述信息
    return {
        "name": "Hello-MCP",
        "version": "1.0.0",
        "description": "这是一个MCP 服务器",
    }


# 注册一个 prompt，名称为 welcome，返回欢迎信息
@mcp.prompt("welcome")
async def get_welcome():
    # 返回欢迎信息
    return "欢迎使用 MCP 服务器！我是你的 AI 助手。"


# 定义客户端逻辑，自动启动服务器并进行连通性测试
async def run_client():
    # 构造 stdio 服务器参数，指定用 python 运行本文件并传递 "serve" 参数
    server_params = StdioServerParameters(command="python", args=[__file__, "serve"])

    # 以异步方式连接到 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("[Tools]", [t.name for t in tools.tools])

            # 获取并打印所有资源 URI
            resources = await session.list_resources()
            print("[Resources]", [r.uri for r in resources.resources])

            # 获取并打印所有 prompt 名称
            prompts = await session.list_prompts()
            print("[Prompts]", [p.name for p in prompts.prompts])

            # 调用 hello 工具
            result = await session.call_tool("hello", arguments={})
            # 提取并打印返回的文本内容
            tool_texts = []
            for block in result.content:
                # 判断内容块是否为文本类型
                if isinstance(block, types.TextContent):
                    tool_texts.append(block.text)
            # 打印 hello 工具的返回内容
            print(
                "[Call hello]", " | ".join(tool_texts) or str(result.structuredContent)
            )

            # 获取 resource 内容
            resource_texts = []
            for resource in resources.resources:
                # 读取每个资源的内容
                resource_result = await session.read_resource(resource.uri)
                for block in resource_result.contents:
                    # 判断内容块是否为文本资源类型
                    if isinstance(block, types.TextResourceContents):
                        resource_texts.append(block.text)
                # 打印每个资源的内容
                print(f"[Resource: {resource.uri}]", " | ".join(resource_texts))

            # 获取 prompt 内容
            prompt_texts = []
            for prompt in prompts.prompts:
                # 获取每个 prompt 的内容
                prompt_result = await session.get_prompt(prompt.name)
                for message in prompt_result.messages:
                    # 判断消息是否为 PromptMessage 类型
                    if isinstance(message, types.PromptMessage):
                        prompt_texts.append(message.content.text)
                # 打印每个 prompt 的内容
                print(f"[Prompt: {prompt.name}]", " | ".join(prompt_texts))


# 服务器入口：当以 "serve" 参数运行时，启动服务器
def run_server_stdio():
    # 打印服务器启动信息
    print("启动 MCP 服务器（stdio 模式）...")
    # 以 stdio 方式运行 MCP 服务器
    mcp.run(transport="stdio")


# 主函数：根据参数决定运行模式
def main():
    # 导入 sys 模块以获取命令行参数
    import sys

    # 判断命令行参数是否为 "serve"
    if len(sys.argv) >= 2 and sys.argv[1] == "serve":
        # 服务器模式：运行 stdio 传输
        run_server_stdio()
    else:
        # 客户端模式：启动服务器并连接，然后做连通性检查
        print("启动 MCP 客户端测试...")
        print("将自动启动服务器进程并测试连接")
        # 运行客户端测试逻辑
        asyncio.run(run_client())


# 如果作为主程序运行，则调用 main 函数
if __name__ == "__main__":
    main()

运行步骤（在 C:\mcp-project 目录）：

cd C:/mcp-project
python check_mcp_setup.py

预期输出：

启动 MCP 客户端测试...
将自动启动服务器进程并测试连接
[Tools] ['hello']
[Resources] [AnyUrl('mcp://info')]
[Prompts] ['welcome']
[Call hello] Hello from MCP server!
[Resource: mcp://info] {
  "name": "Hello-MCP",
  "version": "1.0.0",
  "description": "这是一个MCP 服务器"
}
[Prompt: welcome] 欢迎使用 MCP 服务器！我是你的 AI 助手。

若能看到类似输出，说明 SDK 安装与基本交互链路正常。

5.核心组件 #

5.1. FastMCP服务器框架 #

from mcp.server.fastmcp import FastMCP

# 创建 MCP 服务器实例
mcp = FastMCP(name="Hello-MCP")

作用：

• 提供高级的 MCP 服务器实现
• 自动处理协议细节（序列化、反序列化、消息路由）
• 提供装饰器语法注册工具、资源和提示

核心方法：

@mcp.tool()           # 注册工具
@mcp.resource(uri)    # 注册资源
@mcp.prompt(name)     # 注册提示

mcp.run(transport="stdio")  # 启动服务器

5.2. StdioServerParameters服务器连接参数 #

from mcp import StdioServerParameters

server_params = StdioServerParameters(
    command="python",           # 启动服务器的命令
    args=[__file__, "serve"],   # 命令参数
    env={}                      # 环境变量
)

作用：

• 定义如何启动和连接到 MCP 服务器
• 支持 stdio（标准输入输出）传输方式
• 可以启动本地进程或连接到远程服务器

参数说明：

• command: 启动服务器的命令（如 python、node、java 等）
• args: 命令参数列表
• env: 环境变量字典

5.3. stdio_client客户端连接器 #

from mcp.client.stdio import stdio_client

async with stdio_client(server_params) as (read, write):
    # read: 从服务器读取数据的流
    # write: 向服务器写入数据的流

作用：

• 建立与 MCP 服务器的 stdio 连接
• 返回读写流，用于数据交换
• 自动处理连接的生命周期管理

工作流程：

1. 启动服务器进程
2. 建立 stdio 管道
3. 返回读写流
4. 连接关闭时自动清理

5.4. ClientSession客户端会话 #

from mcp import ClientSession

async with ClientSession(read, write) as session:
    # 使用 session 与服务器交互

作用：

• 提供高级的 MCP 客户端 API
• 管理协议状态和会话信息
• 处理工具调用、资源读取、提示获取等操作

核心方法：

await session.initialize()                    # 初始化协议
await session.list_tools()                    # 列出所有工具
await session.list_resources()                # 列出所有资源
await session.list_prompts()                  # 列出所有提示
await session.call_tool(name, arguments)      # 调用工具
await session.read_resource(uri)              # 读取资源
await session.get_prompt(name)                # 获取提示

5.5. types类型定义 #

from mcp import types

# 检查内容块类型
if isinstance(block, types.TextContent):
    texts.append(block.text)

作用：

• 定义 MCP 协议中使用的数据结构
• 提供类型检查和内容提取功能
• 确保协议兼容性

主要类型：

types.TextContent       # 文本内容
types.ImageContent      # 图像内容
types.EmbeddedResource  # 嵌入资源
types.DataContent       # 数据内容

5.6. 完整工作流程 #

5. 常见问题（FAQ） #

• mcp 命令不存在：
  • 确认已在当前虚拟环境中安装 mcp[cli]，并已 call .venv\Scripts\activate
• Python 版本不满足：
  • 使用 python --version 确认 3.10+，建议更新。
• 端口占用：
  • 更换端口或关闭占用进程。