🧠 基于 Python 的 MCP 服务器 – 实践教程

本仓库演示了如何使用 Microsoft 官方 Python SDK 创建一个 MCP (Model Context Protocol) 服务器。该项目展示了如何定义可以被 LLM（如 ChatGPT）或 Open WebUI 等环境中的模型使用的工具 (@tool)。

---

🚀 使用的技术

• Python 3.10+
• uv – 环境和包管理
• mcp – 官方 MCP SDK
• mcpo – HTTP 中间件 + OpenAPI 文档

---

⚙️ 安装

# 1. 使用 uv 创建虚拟环境
uv venv .venv
source .venv/bin/activate

# 2. 安装 MCP SDK, CLI 和 mcpo
uv add mcp mcp[cli] mcpo

---

🧩 项目结构

📁 项目/
├── main.py         # 包含 MCP 服务器的主文件
├── README.md       # 本文件
└── .venv/          # 虚拟环境 (不要版本控制)

---

🛠️ 代码示例 – main.py

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MCP 教程")

@mcp.tool()
def get_tutorial_summary():
    """
    返回 MCP 服务器教程的摘要

    :return: 关于如何构建 MCP 服务器的文本摘要。
    """
    return (
        "使用 uv 配置环境。\n"
        "使用以下命令安装：uv add mcp mcp[cli] mcpo\n"
        "使用 @tool 实现函数\n"
        "使用 mcpo 执行\n"
        "通过 MCP 客户端或 Open WebUI 使用。"
    )

@mcp.tool()
def somar(a: int, b: int) -> int:
    """
    将两个整数相加并返回结果。

    :param a: 第一个数字。
    :param b: 第二个数字。
    :return: a 和 b 的总和结果。
    """
    return a + b

if __name__ == "__main__":
    mcp.run(transport="stdio")  # 本地执行

---

▶️ 如何运行

🔹 1. 本地模式 (stdio)

.venv/bin/python main.py

或者

mcp run main.py # 以默认方式运行服务器

mcp dev main.py # 在开发者模式下测试服务器

mcp install main.py # 在 Claude Desktop 中本地安装

此模式非常适合使用 MCP CLI 进行本地测试。

---

🔹 2. 使用 mcpo 的 HTTP 模式，用于 OpenAPI 文档和集成到 OpenWebUI

mcpo --port 8000 -- .venv/bin/python main.py

• 访问交互式文档： 👉 http://localhost:8000/docs

• 现在，服务器可用作 RESTful API。

---

🤖 与 Open WebUI 集成

使用 mcpo 启动服务器后，您可以将其连接到 Open WebUI 或其他支持 MCP 协议的 LLM 工具。

1. 转到您的 Open WebUI 实例
2. 转到设置
3. 点击 Tools
4. 输入新的 MCP 服务器的 URL：http://localhost:8000

有关更多信息，请单击此处。

---

📘 关于函数中的 docstring

每个 @mcp.tool() 都应包含清晰完整的 docstring，因为：

• 它会自动出现在 OpenAPI 文档中。
• AI 使用它来根据用户对 AI 的查询/提问来决定使用哪个函数。

🔥 编写良好的 docstring 可以大大提高 LLM 的可用性。

---

📢 贡献

欢迎提交 Pull Request！ 随意建议新的工具，改进示例或扩展教程。