easy-mcp-kit Skill 技能

easy-mcp-kit：像写函数一样构建 MCP 服务器

什么是 easy-mcp-kit

easy-mcp-kit 是一个用于快速构建 MCP（Model Context Protocol）服务器的 Python 库。它的定位是"FastAPI 之于 HTTP API"——你只需要写一个普通的 Python 函数，加上装饰器，就能得到一个完整的、符合 MCP 协议规范的服务器。架构层面的 schema 生成、参数校验、身份认证、限流、日志、错误处理全部由框架内置完成，开发者只需专注业务逻辑本身。

核心能力

1. 装饰器驱动，自动生成工具 schema 用 @server.tool 装饰一个普通函数，框架自动从函数签名（类型提示）和文档字符串生成完整的 JSON Schema 描述。参数说明从 docstring 的 Args: 段落或 Annotated 类型注解中提取，无需手写任何 schema 配置文件。

2. 参数自动校验，拒绝脏数据 框架在调用你的函数之前，先用生成的 schema 做严格校验：未知字段、类型错误、必填参数缺失都会被拦截在函数执行之前，防止业务代码收到不合法的输入。

3. 内置身份认证与作用域控制 通过 auth=APIKeyAuth 为工具绑定 API Key 校验，支持按客户端分配不同权限作用域，受保护的工具在未授权时对客户端完全隐藏，而不是返回错误。

4. 滑动窗口限流 在装饰器参数中写 rate_limit_per_minute=120，框架自动为每个客户端维护独立的滑动窗口计数器，防止单个客户端压垮服务器。

5. 结构化输出与 Rich Schema 函数返回 Pydantic 模型时，框架自动发布其完整 schema，并在 MCP 响应中使用 structuredContent 字段返回结构化数据，客户端可以直接解析而非正则匹配文本。

6. 多种运行模式 一行 server.run() 启动 HTTP 服务器（默认 8000 端口），连接地址 http://127.0.0.1:8000/mcp；换成 server.run("stdio") 则输出 stdio 协议，适合 Claude Desktop、Claude Code、Cursor、Cline 等桌面 MCP 宿主。

7. 安全的错误处理 函数中 raise 的异常会被框架自动捕获、清洗（不泄露堆栈），以标准化格式返回给客户端，不会因为未处理异常导致连接断开。

8. 纯 Python，最少依赖 仅依赖 starlette 和 uvicorn，Python 3.11+ 即可运行。无需 Node.js，无需编译，拿来即用。

安装配置

环境要求

• Python 3.11 及以上
• starlette、uvicorn（由 easy-mcp-kit 自动安装）

安装命令 pip install easy-mcp-kit 导入名称为 easy_mcp，包名称为 easy-mcp-kit。

基础配置示例

from easy_mcp import MCPServer

server = MCPServer(port=8000)

@server.tool
def add(a: int, b: int) -> int:
    return a + b

server.run()

上述代码启动一个 HTTP MCP 服务器，客户端连接 http://127.0.0.1:8000/mcp 后即可发现并调用 add 工具。

带身份认证的配置

from easy_mcp import MCPServer, APIKeyAuth

server = MCPServer(port=8000, auth=APIKeyAuth({
    "client_a": {"scopes": ["read"]},
    "client_b": {"scopes": ["read", "write"]},
}))

@server.tool(scope="write")
def delete_records(ids: list[str]) -> dict:
    pass

带限速的配置

@server.tool(rate_limit_per_minute=60)
def heavy_query(sql: str) -> list[dict]:
    pass

使用步骤

第一步：安装依赖 pip install easy-mcp-kit

第二步：定义工具函数

from easy_mcp import MCPServer

server = MCPServer(port=8000)

@server.tool
def weather(city: str) -> dict:
    return {"city": city, "temp": 22, "condition": "晴"}

第三步：选择运行模式并启动 HTTP 服务器模式：server.run() # 监听 8000 端口 Stdio 模式（Claude Code / Cursor 常用）：server.run("stdio")

第四步：配置 MCP 客户端 以 Claude Desktop 为例，在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "my-server": {
      "command": "uvicorn",
      "args": ["my_module:app", "--port", "8000"]
    }
  }
}

其中 my_module.py 包含上述 server 定义，并暴露 app = server.app。

适用场景

1. 构建企业内部工具服务 将内部系统的 API 封装为 MCP 工具，让 AI 助手直接调用内部数据查询、审批流程等操作，无需将 API 密钥暴露给 AI 模型。

2. 快速原型验证 MCP 协议 在学习和实验 MCP 协议时，easy-mcp-kit 提供最快上手路径：写一个函数就能看到协议交互，不需要理解底层握手和传输层细节。

3. 为现有 Python 脚本添加 MCP 接口 已有 Python 脚本或数据处理流程，用装饰器包装函数即可对外提供 MCP 工具，旧代码几乎不用改。

4. 构建多租户 AI 工具平台 通过内置的 API Key 认证和限流机制，可以安全地为多个租户提供独立的 MCP 工具接入点。

适用人群

• AI 应用开发者：需要为 AI 助手快速构建可靠工具接口
• 后端工程师：已有 Python 微服务，想以最小成本扩展为 MCP 工具
• AI Agent 框架开发者：在自建 Agent 框架中集成 MCP 协议支持
• 技术爱好者：学习 Model Context Protocol 协议的最佳实践工具

工作原理

easy-mcp-kit 基于 FastAPI 构建，本质是一个特殊的 ASGI 应用。当 MCP 客户端通过 HTTP POST 请求发送 tools/call 调用时，框架执行以下流程：

1. 请求解析：从 JSON body 提取工具名和参数
2. 认证校验：若工具配置了 auth，验证请求中的 API Key
3. 限流检查：更新滑动窗口计数器，超限则返回 429
4. 参数校验：用函数签名生成的 JSON Schema 做严格校验，不通过则返回错误
5. 函数执行：调用目标函数，捕获返回值或异常
6. 结果序列化：正常返回序列化为 structuredContent；异常被清洗后返回
7. 日志记录：每次调用生成结构化日志，包含调用者、参数、执行时间、结果状态

整个过程中，开发者只需要写第 5 步的函数逻辑，其余环节框架自动完成。

官方链接

• PyPI 主页：https://pypi.org/project/easy-mcp-kit/
• GitHub 仓库：https://github.com/Mark007-R/Easy-MCP