MCP Python SDK学习指南

MCP Python SDK学习指南

摘要

本文将详细介绍 Model Context Protocol（MCP）Python SDK 的使用方法和核心概念。MCP 是一种用于将外部数据源和工具与大型语言模型（LLM）应用集成的开放协议。通过 MCP，开发者可以构建 MCP 客户端连接到任何 MCP 服务器，创建暴露资源、提示和工具的 MCP 服务器，并处理所有 MCP 协议消息和生命周期事件。本文将涵盖 MCP 的安装、快速入门、核心概念、服务器运行方式、示例以及高级用法等内容。

一、概述

MCP Python SDK 实现了完整的 MCP 规范，使开发者能够轻松地构建 MCP 客户端和服务器。它支持标准传输如 stdio、SSE 和 Streamable HTTP，并且能够处理所有 MCP 协议消息和生命周期事件。

二、安装

（一）添加 MCP 到 Python 项目

推荐使用 uv 来管理 Python 项目。如果尚未创建 uv 管理的项目，可以按照以下步骤创建：

uv init mcp-server-demo
cd mcp-server-demo

然后将 MCP 添加到项目依赖项中：

uv add "mcp[cli]"

对于使用 pip 管理依赖项的项目，可以运行以下命令：

pip install "mcp[cli]"

（二）运行独立的 MCP 开发工具

使用 uv 运行 mcp 命令：

uv run mcp

三、快速入门

下面创建一个简单的 MCP 服务器，它暴露了一个计算器工具和一些数据：

# server.py
from mcp.server.fastmcp import FastMCP

# 创建一个 MCP 服务器
mcp = FastMCP("Demo")


# 添加一个加法工具
@mcp.tool()
def add(a: int, b: int) -> int:
    """添加两个数字"""
    return a + b


# 添加一个动态问候资源
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """获取个性化问候"""
    return f"Hello, {
     
     name}!"

可以通过以下命令将此服务器安装到 Claude Desktop 并立即与其交互：

mcp install server.py

或者，可以使用 MCP Inspector 进行测试：

mcp dev server.py

四、核心概念

（一）服务器

FastMCP 服务器是与 MCP 协议交互的核心接口。它处理连接管理、协议合规性和消息路由。以下是一个示例：

# 添加生命周期支持以启用启动/关闭和强类型
from contextlib import asynccontextmanager
from collections.abc import AsyncIterator
from dataclasses import dataclass

from fake_database import Database  # 替换为实际的数据库类型

from mcp.server.fastmcp import Context, FastMCP

# 创建一个命名服务器
mcp = FastMCP("My App")

# 指定部署和开发的依赖项
mcp = FastMCP("My App", dependencies=["pandas", "numpy"])


@dataclass
class AppContext:
    db: Database


@asynccontextmanager
async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
    """使用类型安全的上下文管理应用程序生命周期"""
    # 启动时初始化
    db = await Database.connect()
    try:
        yield AppContext(db=db)
    finally:
        # 关闭时清理
        await db.disconnect()


# 将生命周期传递给服务器
mcp = FastMCP("My App", lifespan=app_lifespan)


# 在工具中访问类型安全的生命周期上下文
@mcp.tool()
def query_db(ctx: Context) -> str:
    """使用初始化资源的工具"""
    db = ctx.request_context.lifespan_context.db
    return db.query()

（二）资源

资源是向 LLM 暴露数据的方式，类似于 REST API 中的 GET 端点。它们提供数据，但不应执行大量计算或产生副作用。示例如下：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My App")


@mcp.resource("config://app")
def get_config() -> str:
    """静态配置数据"""
    return "App 配置信息"


@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """动态用户数据"""
    return f"用户 {
     
     user_id} 的个人资料数据"

（三）工具

工具允许 LLM 通过服务器执行操作。与资源不同，工具预期会执行计算并产生副作用。示例代码如下：

import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("My App")


@mcp.tool()
def calculate_bmi(weight_kg: float, height_m: float) -> float:
    """根据体重（千克）和身高（米）计算 BMI"""
    return weight_kg / (height_m**2)


@mcp.tool()
async def fetch_weather(city: str) -> str:
    """获取城市的当前天气"""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.weather.com/{
     
     city}")
        return response.text

（四）提示

提示是可重用的模板，可帮助 LLM 有效地与服务器交互。示例如下：

from mcp.server.fastmcp import FastMCP
from mcp.server.fastmcp.prompts import base

mcp = FastMCP(