Building a Simple MCP Server in Python Using the MCP Python SDK

使用 MCP Python SDK 在 Python 中构建简单的 MCP 服务

Model Context Protocol（MCP）是一种向大语言模型（LLM）提供上下文的标准化方式。使用 MCP Python SDK，你可以构建服务，以安全且模块化的方式向 LLM 应用提供数据（资源）、功能（工具）和交互模板（提示词）。在本教程中，我们将逐步在 Python 中构建一个简单的 MCP 服务。

简介

Model Context Protocol（MCP）统一了应用与 LLM 之间的接口。借助 MCP，你可以将提供上下文、执行代码和管理用户交互这几项职责分开。MCP Python SDK 实现了完整的 MCP 规范，让你能够：

• 提供资源： 向 LLM 提供数据（类似 GET 端点）。
• 定义工具： 提供可执行操作或计算的功能（类似 POST 端点）。
• 创建提示词： 提供可重复使用的模板化交互。

MCP 基元

每个 MCP 服务都可以实现三种核心基元。这些基元定义了由谁控制调用，以及每种基元发挥什么作用：

基元	控制方	描述	示例用途
提示词	用户控制	由用户选择触发的交互模板	斜杠命令、菜单选项
资源	应用控制	由客户端应用管理的上下文数据	文件内容、API 响应
工具	模型控制	提供给 LLM 以执行操作的函数	API 调用、数据更新

• 提示词让你能够定义_结构化_的对话开场白。
• 资源类似于为 LLM 上下文提供的只读数据端点。
• 工具让 LLM 能够执行操作——计算、获取和更新。

---

服务能力

初始化期间，MCP 服务会公布其支持的功能。客户端（及前端）可以根据这些标志动态调整：

能力	功能标志	描述
prompts	listChanged	提示词模板管理
resources	subscribe listChanged	资源提供和实时更新
tools	listChanged	工具发现和执行
logging	–	服务日志配置
completion	–	参数补全建议

• listChanged 表示可用提示词／资源／工具的集合可能在运行时发生变化。
• subscribe 允许客户端在资源数据发生变化时注册接收更新。
• logging 和 completion 是用于调试输出和自动补全辅助的简单开关。

本教程将引导你使用 MCP Python SDK 创建一个简单的 MCP 服务。

前提条件

开始之前，请确保已安装以下内容：

• Python 3.7+（建议使用 3.11 或更高版本）
• pip – Python 包安装程序
• Node.js 18.x

你还需要安装 MCP Python SDK。可选择以下两种方式：

• 直接使用 pip：

  pip install "mcp[cli]"
  

• 使用 uv：
  如果你使用 uv 管理项目，请初始化项目并将 MCP 添加为依赖项。

  uv init mcp-server
  cd mcp-server
  uv add "mcp[cli]"
  

如需更详细的安装说明，请查阅 MCP Python SDK 文档。

设置环境

本节将详细介绍如何在 Ubuntu 22.04 上使用 Python 3.11 设置开发环境，确保安装了正确的 Python 版本和 MCP Python SDK。

选项 1：手动安装 如果你更喜欢按步骤操作，请按照以下说明进行：

1. 添加 deadsnakes PPA： 此仓库为 Ubuntu 提供较新的 Python 版本。

   sudo add-apt-repository ppa:deadsnakes/ppa -y
   

2. 更新软件包列表：

   sudo apt update
   

3. 安装 Python 3.11 和必要工具：

   sudo apt install -y python3.11 python3.11-venv python3.11-distutils python3-apt
   

   • python3.11：Python 3.11 解释器。
   • python3.11-venv：Python 3.11 的虚拟环境模块。
   • python3.11-distutils：用于构建和安装 Python 软件包的必要工具。
   • python3-apt：APT 软件包管理系统的 Python 接口（有助于解决潜在的依赖问题）。

4. 将 Python 3.11 设为默认的 python3（可选，但建议执行）： 这样可以简化 Python 3.11 的使用，无需每次都指定 python3.11。

   sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1
   sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 2
   sudo update-alternatives --config python3
   

   系统会提示你选择默认的 Python 3 版本。请选择 Python 3.11。

5. 为 Python 3.11 安装 pip： pip 是 Python 的软件包安装程序。

   curl -sS https://bootstrap.pypa.io/get-pip.py | sudo python3.11
   

6. 验证 Python 和 pip 版本：

   python3 --version
   python3 -m pip --version
   

   确认输出显示 Python 3.11 和较新版本的 pip。

7. 为 Node.js 18.x 配置 NodeSource…

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

正在安装 Node.js（包括 npm 和 npx）…"

sudo apt-get update
sudo apt-get install -y nodejs

9. 创建并激活虚拟环境： 使用虚拟环境可以隔离项目的依赖项。

   python3 -m venv .venv
   source .venv/bin/activate
   

   项目中将创建一个 .venv 目录，并且终端提示符会变为 (.venv)，表示环境已激活。

10. 在虚拟环境中升级 pip：

    pip install --upgrade pip
    

11. 安装 MCP Python SDK： 在项目目录中创建名为 requirements.txt 的文件，并写入以下内容：

    mcp[cli]
    

    然后使用 pip 安装 SDK：

    pip install -r requirements.txt
    

选项 2：使用 install.sh 脚本

如需更自动化的设置，可以使用提供的 install.sh 脚本。

1. 保存脚本： 确保将之前提供的脚本保存为项目目录中的 install.sh。

2. 使脚本可执行： 打开终端，切换到项目目录，然后运行：

   chmod +x install.sh
   

3. 运行脚本： 执行脚本：

   bash install.sh
   

   install.sh 脚本会自动完成手动安装步骤：

   • 添加 deadsnakes PPA 并更新软件包列表。
   • 安装 Python 3.11 和必要工具。
   • 将 Python 3.11 设为默认的 python3。
   • 为 Python 3.11 安装 pip。
   • 创建并激活名为 .venv 的虚拟环境。
   • 在虚拟环境中升级 pip。
   • 安装 Node.js：node v18.20.8
   • 从 requirements.txt 安装 MCP Python SDK（如果该文件存在）。

重要说明：

• 无论选择哪种方法，每次在新的终端会话中处理项目时，都要激活虚拟环境（source .venv/bin/activate）。这样可以确保使用正确的 Python 版本，并能访问已安装的 MCP SDK。
• install.sh 脚本专为 Ubuntu 22.04 设计。如果你使用其他操作系统或发行版，可能需要相应调整脚本。
• requirements.txt 文件对于管理项目依赖至关重要。请始终确保其中包含所需的软件包。

环境设置完成后，就可以创建 MCP 服务了！

---

设置项目

为项目创建一个新目录并进入该目录。然后，在项目根目录中创建一个名为 server.py 的文件。

项目结构应如下所示：

mcp-server/
├── server.py
└── (other files such as .env, README.md, etc. as needed)

创建 MCP 服务

在本节中，我们将创建一个简单的 MCP 服务，其中包含一个计算器工具和一个动态问候资源。之后，你可以使用提示词或其他工具来扩展其功能。

定义工具

工具是用于执行计算或产生副作用的函数。在此示例中，我们将定义一个简单的加法工具。

打开 server.py 并添加以下代码：

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

# Create an MCP server instance with a custom name.
mcp = FastMCP("Demo Server")

# Add a calculator tool: a simple function to add two numbers.
@mcp.tool()
def add(a: int, b: int) -> int:
    """
    Add two numbers together.
    
    :param a: First number.
    :param b: Second number.
    :return: Sum of the numbers.
    """
    return a + b

暴露资源

资源提供可加载到大模型上下文中的数据。在这里，我们将定义一个返回个性化问候语的资源。

将以下代码添加到 server.py：

# Expose a greeting resource that dynamically constructs a personalized greeting.
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """
    Return a greeting for the given name.
    
    :param name: The name to greet.
    :return: A personalized greeting.
    """
    return f"Hello, {name}!"

添加提示词（可选）

提示词允许你提供可重复使用的交互模板。例如，你可以添加一个用于审查代码的提示词。

如有需要，添加以下代码：

from mcp.server.fastmcp.prompts import base

@mcp.prompt()
def review_code(code: str) -> str:
    """
    Provide a template for reviewing code.
    
    :param code: The code to review.
    :return: A prompt that asks the LLM to review the code.
    """
    return f"Please review this code:\n\n{code}"

运行 MCP 服务

首先，运行以下命令，确保已激活 Python 虚拟环境：

source .venv/bin/activate

请在项目根目录中执行此操作。然后，进入 MCP 服务文件夹：

cd mcp-server

在 server.py 中定义好服务后，就可以运行它了。根据开发、调试、集成或部署等目标，运行 MCP 服务的方式有多种。

运行和测试服务的最佳方式：使用 mcp dev

与 MCP 服务交互最简单的方式是使用内置的 MCP Inspector，它会在浏览器中提供可视化界面。

在开发和测试期间，MCP Development Inspector 会提供直观的 Web 界面，方便你与服务交互。

1. 以开发模式启动服务

在终端中运行：

mcp dev server.py

此命令会启动 MCP 服务，通常还会在 Web 浏览器中打开 Inspector。你会看到“Demo Server”以及已公开的工具（add）、资源（greeting）和提示词（review_code）。

1. 使用 Inspector 启动服务：

   mcp dev server.py
   

2. 它会执行几项重要任务：

• 使用默认的 STDIO 传输方式启动 MCP 服务。
• **启用实时重新加载，**这样代码更新会立即生效，无需重启服务。
• **启动 MCP Inspector 界面，**这是一个基于 Web 的 UI，可通过 http://localhost:6274/ 访问，你可以在其中探索并测试服务的所有功能。

运行命令后，终端输出应类似于：

此输出表明 Inspector 已启动，可以开始交互。

1. 在 UI 中，你可以：
   • 测试 add(a, b) 工具
   • 使用 greeting://John 测试资源
   • 使用 review_code 提示词审查代码

💡 如果缺少软件包，mcp dev 会帮助你自动安装。

使用 MCP Inspector 界面

2. 通过 Inspector 交互

在浏览器中打开 Inspector 后，你会看到几个用于简化服务测试的关键部分。

前往 MCP Inspector 界面顶部，找到以下内容：

Transport Type: STDIO  
Command: python  
Arguments: run --with mcp mcp run server.py

由于我们的 server.py 是一个独立脚本，使用基于常规 pip 的虚拟环境，因此我们需要在 MCP Inspector 中更正配置：

Transport Type: STDIO  
Command: python  
Arguments: server.py

然后点击 Connect，我们的服务就会使用 Python 解释器正常启动。

示例用法：测试“Add”工具

• 调用工具（add）： 在 Inspector 中找到 add 工具。

使用我们的示例（其中注册了一个加法工具、一个问候资源和一个代码审查提示词）时，请考虑以下场景：

1. 访问 Tools 选项卡：
   加载 MCP Inspector 后，前往 Tools 选项卡。点击 List Tools。此处会显示服务中注册的所有工具。在我们的示例中，其中一项就是 add 工具。

2. 测试“Add”功能：
   从列表中点击 add 工具。Inspector 会显示该工具的输入架构，并提示你输入两个数字（例如，参数 a 和 b）。

   • 输入参数： 输入 a = 10 和 b = 15。
   • 执行： 点击 Inspector 执行面板中的执行按钮。

3. 查看输出：
   执行后，Inspector 会立即显示运算结果。你应该会看到返回的总和为 25。
   这种即时反馈循环展示了你如何在不离开开发界面的情况下，快速验证工具逻辑是否按预期运行。

通过 MCP Inspector 使用 review_code 提示词

• 在 Inspector 的侧边栏中，展开 Prompts → List prompts。
• 你应该会看到 review_code：

  review_code

在提示词面板中，你会看到一个可用于输入参数的表单或 JSON 编辑器。

2. 提供 code 参数。 例如：

print(1+1)

点击 Run Tool。

查看生成的提示词

Inspector 会显示输出：

{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Please review this code:\n\nprint(1+1)"
      }
    }
  ]
}

访问资源（greeting://Alice）

使用上述设置在 Inspector 中启动并运行服务后，你可以通过 URI 调用任何已注册的资源：

1. 打开资源交互面板

• 在 MCP Inspector 侧边栏中，点击 Resources → Resource Templates。 点击 List templates，然后选择 get_greeting

2. 输入资源 URI

• 在输入字段中，输入：

Alice

3. 调用资源

• 点击 Read Resource。
• Inspector 会将该 URI 发送给你的 @mcp.resource("greeting://{name}") 处理程序。

4. 查看响应

• 你应该会看到：

{
  "contents": [
    {
      "uri": "greeting://Alice",
      "mimeType": "text/plain",
      "text": "Hello, Alice!"
    }
  ]
}

• 这可以确认动态问候资源已正确接入，并能按需返回个性化输出。

MCP Inspector 充当了一个易用的客户端，为你处理底层协议通信。

运行 python server.py 时会发生什么

你的代码是正确的，但运行以下命令时：

python server.py

……看起来似乎什么都没发生。这是因为你的服务默认使用 stdio（标准输入/输出） 作为传输方式，并且会静静地等待客户端连接并向其发送请求。

这很正常！但你需要使用正确的界面与它交互。

🐍 使用 Python MCP 客户端（client.py）

如需以编程方式交互，你可以使用 mcp Python SDK 创建客户端。你提供的 client.py 就是一个正确示例：

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

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )

    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()

            result = await session.call_tool("add", arguments={"a": 3, "b": 4})
            print(f"Result of add tool: {result}")

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

运行此客户端：

1. 启动服务：

   python server.py
   

2. 在另一个终端中运行客户端：

    python client.py

输出如下：

[your log output indicating the tool call]
Result of add tool: meta=None content=[TextContent(type='text', text='7', annotations=None)] isError=False

这展示了 Python 客户端如何连接到你的服务，并以编程方式调用工具。

总结

在本教程中，我们使用 MCP Python SDK 在 Python 中构建了一个简单的 MCP 服务。我们：

• 设置了项目并安装了 MCP SDK。
• 创建了一个 MCP 服务，提供计算器工具和动态问候资源。

MCP Python SDK 让你能够构建稳健、模块化的服务，为大模型应用提供数据、功能和可复用的交互模板。扩展服务时，可以考虑添加更复杂的工具、资源和提示词，充分发挥 Model Context Protocol 的强大能力。