开发一个MCP(Model Context Protocol)服务器需要遵循标准协议,结合代码实现和工具配置。以下是基于Python技术栈的MCP Server开发步骤及关键要点,综合了多个实践案例与官方文档建议:
一、环境准备
安装Python与MCP SDK
- Python版本需≥3.10(推荐3.10+),使用
pip
安装MCP库:
bash
python -m venv mcp-env # 推荐使用虚拟环境
source mcp-env/bin/activate #Linux/Mac
pip install mcp
- 验证安装:
mcp version
应返回版本号(如1.5.0)。
选择开发工具
支持MCP的客户端(如Cline、Cursor、Claude Desktop)用于测试,或使用调试工具如MCP Inspector
。
二、核心开发步骤
定义工具函数(Tools)
- 使用
@mcp.tool()
装饰器暴露函数能力,并通过文档字符串描述功能(供大模型理解用途):
python
# custom_mcp.py
from mcp.server.fastmcp import FastMCP
import os
mcp = FastMCP()
@mcp.tool()
def list_desktop_files() -> list:
"""获取当前用户桌面上的所有文件列表(macOS专属实现)"""
desktop_path = os.path.expanduser("~/Desktop")
return os.listdir(desktop_path)
@mcp.tool()
def say_hello(name: str) -> str:
"""生成个性化问候语(中英双语版)"""
return f"🎉 你好 {name}! (Hello {name}!)"
if __name__ == "__main__":
mcp.run(transport='stdio') # 启用调试模式
- 关键点:工具函数需返回JSON序列化兼容的数据类型(如字符串、列表、字典)。
扩展其他能力
- 资源(Resources):通过URI模板暴露静态或动态数据(如数据库查询结果):
python
@mcp.resource("config://app_settings")
def get_app_config() -> dict:
return {"theme": "dark", "language": "zh-CN"}
- 提示(Prompts):定义与大模型交互的上下文模板(需结合MCP协议规范)。
bash
@mcp.prompt()
def code_review_prompt(code: str) -> str:
return f"请审查以下代码并指出问题:\n\n{code}"
启动与传输配置
选择传输协议:
- 本地通信 :
transport='stdio'
(适合IDE集成)。 - 远程通信 :
transport='sse'
(基于HTTP事件流,需部署为Web服务)。
完整示例
bash
# custom_mcp.py
from mcp.server.fastmcp import FastMCP
import os
mcp = FastMCP()
@mcp.tool()
def list_desktop_files() -> list:
"""获取当前用户桌面上的所有文件列表(macOS专属实现)"""
desktop_path = os.path.expanduser("~/Desktop")
return os.listdir(desktop_path)
@mcp.tool()
def say_hello(name: str) -> str:
"""生成个性化问候语(中英双语版)"""
return f"🎉 你好 {name}! (Hello {name}!)"
@mcp.resource("config://app_settings")
def get_app_config() -> dict:
return {"theme": "dark", "language": "zh-CN"}
@mcp.prompt()
def code_review_prompt(code: str) -> str:
return f"请审查以下代码并指出问题:\n\n{code}"
if __name__ == "__main__":
mcp.run(transport='stdio')
三、客户端配置与测试
配置MCP客户端
- 以CLINE为例,在设置中添加MCP服务器路径(如
cline_mcp_settings.json
):
json
{
"mcpServers": {
"list_desktop_files": {
"command": "python3",
"args": [
"/Users/[USER_NAME]/[YOUR_PATH]/custom_mcp.py"
]
}
}
}
- 刷新客户端后,通过自然语言指令(如"我的桌面有哪些文件")调用工具。
可视化调试
- 使用
MCP Inspector
检查消息交互:
bash
npx @modelcontextprotocol/inspector python custom_mcp.py
- 确保服务器日志输出正常,检查权限与路径限制。
使用npx
运行@modelcontextprotocol/inspector
,如下所示:
打开web服务,可视化调试你所开发的Tools:
四、高级实践与优化
- 安全性控制
- 限制工具访问范围(如仅允许读取特定目录)。
- 使用Nacos等工具管理敏感配置(如API密钥加密)。
- 集成现有API
- 通过Nacos + Higress 方案,将存量HTTP API转换为MCP协议,无需修改代码:
- Nacos注册服务元数据,Higress网关处理协议转换。
- 示例:将高德地图API封装为MCP Server,支持自然语言调用天气查询。
- 通过Nacos + Higress 方案,将存量HTTP API转换为MCP协议,无需修改代码:
- 动态发现与扩展
五、常见问题与解决方案
问题类型 | 解决方案 |
---|---|
工具未被客户端识别 | 检查@mcp.tool() 装饰器及文档字符串格式,确保函数参数和返回值类型明确。 |
传输协议不兼容 | 确认客户端支持的协议类型(如SSE需配置Web服务器)。 |
权限不足 | 限制资源访问路径,使用沙箱环境运行敏感操作。 |
通过上述步骤,开发者可以快速构建一个功能完整的MCP Server,并结合生态工具实现高效集成。更多进阶实践可参考MCP官方文档及社区资源(如AIbase、GitHub示例仓库)。