使用说明

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

ℹ️ 关于本项目

作者：格雷格·莫斯(@gmossy)
最后更新：2025年9月7日
项目存储库: 使用Python的简单MCP服务器

备注：这个项目是我学习模型上下文协议（MCP）和Python服务器开发的一部分。请随时贡献或提供反馈！

ℹ️ macOS用户注意事项

本指南针对macOS进行了优化。虽然核心MCP功能跨平台工作，但某些安装和设置步骤可能因其他操作系统而异。

📚 MCP资源

在我们开始之前，这里有一些有价值的MCP资源：

MCP官方文件 -模型上下文协议综合指南
MCP Python SDK文档 -Python SDK参考和示例
MCP GitHub存储库 -GitHub上的MCP官方组织
MCP规范 -协议技术规范
MCP社区 -获得帮助并与其他MCP开发人员联系

🚀 教程概述

本教程将指导您使用Python 3.12创建一个简单的模型上下文协议（MCP）服务器。MCP是一种为大型语言模型（LLM）提供上下文的标准化方法，允许您构建服务器，以安全和模块化的方式向LLM应用程序公开数据（资源）、功能（工具）和交互模板（提示）。

你将学到什么

如何使用Python 3.12设置MCP服务器
如何定义和公开LLM使用的工具
如何创建和管理提示和资源
如何测试和与MCP服务器交互

用例

构建自定义LLM驱动的应用程序
创建模块化AI助手
在LLM和您的数据/系统之间开发安全接口

MCP简介

模型上下文协议（MCP）标准化了应用程序和LLM之间的接口，允许您分离提供上下文、执行代码和管理用户交互的关注点。MCP Python SDK实现了完整的MCP规范，使您能够：

公开资源： 将数据传递给LLM（类似于GET端点）
定义工具： 提供执行操作或计算的功能（如POST端点）
创建提示： 提供可重用、模板化的交互

MCP图元

每个MCP服务器都可以实现三个核心原语。这些定义 谁控制 调用和作用每个原始元素都扮演：

图元	控件	描述	示例用法
提示	用户控制	用户选择调用的交互式模板	Slash命令、菜单选项
资源	应用程序控制	客户端应用程序管理的上下文数据	文件内容、API响应
工具	模型控制	向LLM公开以执行操作的函数	API调用、数据更新

提示让你定义 结构化的 对话的发起者。
资源类似于LLM上下文的只读数据端点。
工具使LLM能够执行计算、获取、更新等操作。

服务器功能

在初始化过程中，MCP服务器会通告它支持哪些功能。客户端（和前端）可以根据这些标志动态调整：

功能	功能标志	描述
鼓励	`listChanged`	快速模板管理
资源	`subscribe` `listChanged`	资源曝光和实时更新
工具	`listChanged`	工具发现和执行
日志记录	–	服务器日志记录配置
完成	–	论点完成建议

listChanged 表示可用提示/资源/工具集可以在运行时更改的信号。
subscribe 允许客户端在资源数据更改时注册更新。
logging 和 completion 是调试输出和自动完成帮助的简单切换。

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

先决条件

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

Python 3.12+ （优选3.12或更高）
点 Python包安装程序
Node.js 18.x

您还需要安装MCP Python SDK。您有两个选择：

直接使用pip：
```
pip install "mcp[cli]"
```
使用 uv:
如果你正在管理你的项目紫外线，初始化项目并将MCP添加为依赖项。
```
uv init mcp-server
cd mcp-server
uv add "mcp[cli]"
```

有关更详细的安装说明，请查看 MCP Python SDK文档.

快速入门：在Python 3.12中使用uv

如果您正在使用 uv，这里有一个简洁的设置，为这个项目固定Python 3.12并安装依赖项：

# From the repository root
cd mcp-server

# Ensure Python 3.12 is available to uv
uv python install 3.12


- **Python 3.12+** (required)

  ```bash
  # Install Python 3.12 using Homebrew
  brew install python@3.12

紫外线 （Python包管理器和解析器）
```
curl -sSf https://astral.sh/uv/install.sh | sh
```

Node.js 18.x （用于MCP检查器UI）

# Install Node.js 18 using Homebrew
brew install node@18

安装

设置项目环境:

# Navigate to the project directory
cd Simple-MCP-Server-with-Python/mcp-server

# Ensure Python 3.12 is available to uv
uv python install 3.12

# Pin the project to Python 3.12
uv python pin 3.12

# Install dependencies from pyproject/uv.lock
uv sync

验证安装:

mcp --help  # Check if MCP is installed and view available commands

开发工具

对于开发，您需要安装以下基本的Python工具：

pip install ipykernel black flake8

ipykernel：用于Jupyter笔记本支持
黑色：用于一致Python代码风格的代码格式化程序
薄片8：Linter确保代码质量

在macOS上验证您的安装

安装后，请验证您的macOS系统上的所有功能是否正常：

python --version  # Should show Python 3.12.x
mcp --help       # Should show MCP command help if installed

运行MCP服务器

开发模式（推荐）

对于禁用身份验证的开发（更容易测试）：

# From the mcp-server directory
DANGEROUSLY_OMIT_AUTH=true mcp dev server.py

或者使用附带的脚本：

# Make the script executable if you haven't already
chmod +x start_dev_server.sh

# Run the development server
./start_dev_server.sh

生产模式

对于启用身份验证的生产使用：

# From the mcp-server directory
mcp dev server.py

在这两种情况下，这将：

启动MCP服务器
在默认web浏览器中打开MCP检查器
允许您与MCP工具和资源进行交互

MCP检查员将在 http://localhost:6274 在那里你可以测试你的工具和资源。

在Claude桌面应用程序中使用演示服务器

要在Claude桌面应用程序中直接使用MCP服务器：

在Claude中安装服务器：
```
mcp install mcp-server/server.py
```
打开Claude桌面应用程序
您的服务器（默认名为“演示服务器”）将在Claude的界面中可用
现在，您可以在与Claude的对话中直接使用MCP工具

重要提示：

确保激活虚拟环境(source .venv/bin/activate 在macOS/Linux或 .venv\Scripts\activate 在Windows上），每次在新的终端会话中处理项目时。
这 pyproject.toml 和 uv.lock 文件用于管理依赖关系 uv。如果添加新的依赖项，请相应地更新这些文件。
对于开发，MCP检查器提供了一个web界面来测试服务器的功能 http://localhost:6274.

设置好环境后，您就可以创建MCP服务器了！

🛠️ 在macOS上设置项目

为您的项目创建一个新目录并导航到其中。然后，创建一个名为 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

暴露资源

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

将以下代码添加到 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检查员，在浏览器中为您提供可视化UI。

对于开发和测试，MCP development Inspector提供了一个直观的web界面来与您的服务器进行交互。

1.以开发模式启动服务器

在您的终端中，运行：

mcp dev server.py

此命令启动MCP服务器，通常在web浏览器中打开检查器。您将看到您的“演示服务器”和公开的工具(add)，资源(greeting)，并提示(review_code).

使用Inspector启动服务器：
```
mcp dev server.py
```
它执行几个重要任务：

启动MCP服务器 使用默认的STDIO传输。
启用实时重新加载， 因此，您的代码更新会立即应用，而无需重新启动服务器。
启动MCP检查器界面， 基于web的用户界面可在 http://localhost:6274/，您可以在其中探索和测试服务器的所有功能。

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

此输出确认检查器已激活并准备好进行交互。

在UI中，您可以：
- 测试 add(a, b) 工具
- 使用 greeting://John 测试资源
- 使用以下工具查看代码 review_code 提示

💡 如果任何包裹丢失， mcp dev 将帮助您自动安装它们。

导航MCP检查器界面

2.通过检查员进行互动

当您在浏览器中打开检查器时，您会注意到几个旨在促进服务器测试的关键部分。

转到MCP检查器界面的顶部，显示：

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

由于我们 server.py 是一个使用普通脚本的独立脚本 pip-基于虚拟环境，我们需要在MCP检查器中更正配置，以：

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

然后单击连接我们的服务器将使用Python解释器正确启动。

示例用法：测试“添加”工具

调用工具(add): 导航到 add 工具在检查员。

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

访问“工具”选项卡：
加载MCP检查器后，导航到工具选项卡。单击 List Tools。在这里，您将看到服务器上所有已注册工具的列表。在我们的例子中，其中一个条目是 add 工具。
测试“添加”功能：
点击 add 从列表中选择工具。检查器显示工具的输入模式，提示您输入两个数字（例如，参数 a 和 b).
- 输入参数： 进入 a = 10 和 b = 15.
- 执行： 单击检查器执行面板中的执行按钮。
查看输出：
执行后，检查器立即显示操作结果。你应该看到，这笔钱是按以下方式退还的 25.
这个即时反馈循环显示了如何在不离开开发界面的情况下快速验证工具的逻辑是否按预期工作。

使用 `review_code` 通过MCP检查员提示

在检查器的侧栏中，展开提示 → 列表提示.
你应该看看 review_code 上市的：

review_code

在提示窗格中，您将找到一个准备接受参数的表单或JSON编辑器。

供应 code 参数。例如：

print(1+1)

击打 运行工具 .

查看生成的提示

检查器将显示输出：

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

访问资源(`greeting://Alice`)

一旦你的服务器在Inspector中启动并运行（使用上面的设置），你就可以通过URI调用任何注册的资源：

1.打开资源交互窗格

在MCP检查器侧栏中，单击资源 → 资源模板. 点击 List templates 并选择 get_greeting

2.输入资源URI

在输入字段名称中，键入：

Alice

3.调用资源

点击 读取资源.
检查器会将该URI发送到您的 @mcp.resource("greeting://{name}") 处理程序。

4.查看回复

您应该看到：

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

这确认了您的动态问候资源已正确连接，并按需返回个性化输出。

MCP检查器充当用户友好的客户端，为您处理底层协议通信。

怎么回事 `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())

要运行此客户端，请执行以下操作：

启动服务器：
```
python server.py
```
在单独的终端中运行客户端：

    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检查器（推荐）

当您通过以下方式运行检查器时 mcp dev，它会启动一个本地web UI和一个代理。你的Python服务器继续在STDIO上运行；HTTP端口仅用于检查器UI和代理。

检查器UI： http://localhost:6274
代理： http://localhost:6277 （强制执行会话令牌）
服务器传输：STDIO（非HTTP）

One‑liner

从 mcp-server/ 目录：

./start_server.sh

发生了什么：

释放繁忙的检查器端口（6274/6277）
开始 mcp dev server.py 启用身份验证
自动检测打印的“会话令牌：”并打开 http://localhost:6274?token=<TOKEN> 在您的浏览器中

如果您的浏览器没有自动打开，请复制终端中打印的URL并手动打开。

重要提示：使用哪个令牌？

使用由打印的长令牌 mcp dev （检查员令牌）
不要使用 MCP_SESSION_TOKEN 在浏览器中；这是针对程序化客户端的。

禁用身份验证（仅限开发）

对于快速、未经验证的测试：

./start_dev_server.sh

这套 DANGEROUSLY_OMIT_AUTH=true 并开始 mcp dev server.py.

使用相同的令牌运行服务器和客户端

有时，您希望程序化客户端和服务器共享令牌（不带检查器）。

运行客户端（使用相同的令牌通过STDIO生成服务器）：

./run_client.sh --token my-shared-token

或者直接使用令牌运行服务器（无检查器）：

./run_server_env.sh --token my-shared-token

这两个脚本将：

取消设置 DANGEROUSLY_OMIT_AUTH
出口 MCP_SESSION_TOKEN 给定（或生成）值
启动适当的流程

检查器身份验证故障排除

正在使用的端口（6274/6277）：
```
lsof -ti:6274,6277 | xargs kill -9
```
错误的令牌：使用由打印的令牌 mcp dev （检查员令牌），不是 MCP_SESSION_TOKEN.
浏览器缓存：打开私人/隐身窗口或硬刷新(Cmd+Shift+R).
仍然被阻止：将令牌附加到URL，例如：
```
http://localhost:6274?token=<PASTE_TOKEN_HERE>
```

结论

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

设置我们的项目并安装MCP SDK。
创建了一个MCP服务器，该服务器公开了一个计算器工具和一个动态问候资源。

MCP Python SDK使您能够构建健壮的模块化服务器，为LLM应用程序提供数据、功能和可重用的交互模板。在扩展服务器时，考虑添加更复杂的工具、资源和提示，以充分利用模型上下文协议的强大功能。

使用说明

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

ℹ️ 关于本项目

ℹ️ macOS用户注意事项

📚 MCP资源

🚀 教程概述

你将学到什么

用例

MCP简介

MCP图元

服务器功能

先决条件

快速入门：在Python 3.12中使用uv

安装

开发工具

在macOS上验证您的安装

运行MCP服务器

开发模式（推荐）

生产模式

在Claude桌面应用程序中使用演示服务器

🛠️ 在macOS上设置项目

创建MCP服务器

定义工具

暴露资源

添加提示（可选）

运行MCP服务器

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

1.以开发模式启动服务器

导航MCP检查器界面

2.通过检查员进行互动

示例用法：测试“添加”工具

使用 review_code 通过MCP检查员提示

查看生成的提示

访问资源(greeting://Alice)

1.打开资源交互窗格

2.输入资源URI

3.调用资源

4.查看回复

怎么回事 python server.py

🐍 使用Python MCP客户端(client.py)

使用身份验证运行MCP检查器（推荐）

One‑liner

重要提示：使用哪个令牌？

禁用身份验证（仅限开发）

使用相同的令牌运行服务器和客户端

检查器身份验证故障排除

结论

相关 MCP

MySQL查询服务器

Qdrant向量搜索MCP服务器

知识图谱记忆系统

Prometheus MCP 服务器

Python解释器服务

JavaFX绘图协议服务

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

使用 `review_code` 通过MCP检查员提示

访问资源(`greeting://Alice`)

怎么回事 `python server.py`

🐍 使用Python MCP客户端(`client.py`)