从零开始编写与发布MCP Server

核心概念：理解MCP协议

MCP（Model Context Protocol）全称是模型上下文协议。它被定义为AI大模型的标准化工具箱，充当AI与外部工具之间的中间层。MCP Server代替人类访问并操作外部工具，实现AI智能体与复杂工作流。

MCP Server本质上是一段 Node.js 或 Python 程序。大模型通过操作系统的 STDIO（标准输入输出通道）或 SSE 协议调用MCP Server。

准备工作：Python环境与SDK

我们以Python SDK为例，演示MCP Server的创建。第一步是安装 uv，一个高效的Python环境管理工具。

1. 安装 uv

访问 uv 官方安装指南 🔗，根据您的操作系统执行相应命令。

示例 (Windows Powershell):

irm https://astral.sh/uv/install.ps1 | iex

安装完成后，可使用 uv python list 查看已安装的Python版本，或 uv python install 3.13 安装指定版本。

2. 创建 MCP 项目

新建项目文件夹，例如：mcp_server。
进入该文件夹，初始化为Python工程：
```
uv init . -p 3.13
```
安装 MCP Python SDK：
```
uv add "mcp[cli]"
```
使用 VS Code 等IDE打开项目，并安装Python相关插件。

初始化后，项目结构包含 .venv (虚拟环境)、pyproject.toml (项目信息) 和 main.py (基础代码样例)。

编写你的第一个 MCP Server

MCP Server 的编写核心是定义工具 (tool) 和资源 (resource)。

示例代码：一个简单的加法工具

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

# 创建一个MCP server实例
mcp = FastMCP("Demo")

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

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

if __name__ == "__main__":
    mcp.run(transport='stdio') # 默认使用STDIO协议

`@mcp.tool()` 装饰器： 声明下方函数为MCP工具。大模型通过工具与外部系统交互，通常产生副作用（如写入文件、发送邮件）。
`@mcp.resource()` 装饰器： 声明下方函数为MCP资源。资源通常为大模型提供只读数据，不产生副作用，类似于HTTP GET方法。
函数注释 `"""..."""`： 必填！使用自然语言描述函数功能，帮助AI大模型理解和调用。
类型修饰符 `(a: int, b: int) -> int`： 必填！明确参数和返回值的类型，有助于大模型精准传参。
`mcp.run(transport='stdio')`： 启动MCP Server，并指定通信协议。

协议与客户端集成

STDIO 协议 (标准输入输出)

特点： 客户端将MCP Server程序下载到本地运行，AI客户端与MCP Server通过操作系统的标准输入输出通道进行交互。距离更近，通常用于本地开发和测试。

Cherry Studio 配置示例:

类型: stdio
命令: uv
参数: run main.py

SSE 协议 (Server-Sent Events)

特点： MCP Server程序单独部署在服务器上，AI客户端通过SSE协议进行远程调用。距离更远，适用于生产环境部署。

代码修改 (`main.py`):

if __name__ == "__main__":
    mcp.run(transport='sse')

Cherry Studio 配置示例:

类型: SSE
URL: http://[Server IP]:8000/sse

Streamable HTTP 协议

特点： 功能类似SSE，也是用于远程调用。

代码修改 (`main.py`):

if __name__ == "__main__":
    mcp.run(transport='streamable-http')

客户端配置类似SSE，URL末尾改为 `/mcp`。

Cherry Studio Streamable HTTP Configuration

MCP Server 发布上线：让你的工具触达全球

有两种主要方式将MCP Server发布到公网：

方法一：发布到 PyPI (Python Package Index)

将MCP Server打包成Python包并上传到PyPI，用户可使用 uvx 命令自动下载并本地执行。

创建包项目：
```
uv init . --package -p 3.13
```

修改 `__init__.py`： 将MCP Server代码移入，并确保 `mcp.run` 在 `main()` 函数中。

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

mcp = FastMCP("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"

def main() -> None:
    mcp.run(transport='stdio')

打包项目：
```
uv build
```
注册 PyPI 账号并生成 API TOKEN： 访问 pypi.org 🔗，注册并生成API TOKEN（在`Account settings` -> `API Tokens`）。

发布到 PyPI：

uv publish --token pypi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

客户端使用 (Cherry Studio 快速创建):

类型: stdio
命令: uvx
参数: [你的包名]

Cherry Studio PyPI Package Configuration

方法二：部署到公网服务器 (SSE 协议)

将MCP Server程序部署到一台拥有公网IP的云服务器上，并暴露SSE地址供远程调用。

服务器准备： 在Ubuntu等Linux服务器上安装 uv。
```
curl -sSf https://astral.sh/uv/install.sh | sh
```

修改 `main.py` 启用远程访问：

if __name__ == "__main__":
    mcp.settings.host = "0.0.0.0" # 允许远程连接
    mcp.run(transport='sse')

传输代码： 将 `main.py` 和 `pyproject.toml` 传输到服务器目录。

服务器端启动：

uv venv             # 配置虚拟环境
uv pip install .    # 安装项目依赖
uv run main.py      # 启动MCP Server

客户端配置： 将类型设置为 `SSE`，URL指向 `http://[你的服务器公网IP]:8000/sse`。

总结与展望

本教程从零开始，详细介绍了如何使用Python SDK创建MCP Server，涵盖了本地开发与发布上线的四种核心场景：

💡 本地使用 STDIO 🌐 本地使用 SSE 🚀 发布 STDIO (PyPI) ☁️ 发布 SSE (公网服务器)

通过掌握这些知识，你将能够为AI大模型构建和部署强大的外部工具，极大地扩展其功能边界。

目录导航

从零开始编写与发布MCP Server

预览结果：