5分钟手把手教你开发一个MCP服务

开发一个MCP（Model Context Protocol）服务器需要遵循标准协议，结合代码实现和工具配置。以下是基于Python技术栈的MCP Server开发步骤及关键要点，综合了多个实践案例与官方文档建议：

---

一、环境准备

安装Python与MCP SDK

• Python版本需≥3.10（推荐3.10+），使用pip安装MCP库：

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()装饰器暴露函数能力，并通过文档字符串描述功能（供大模型理解用途）：

# 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模板暴露静态或动态数据（如数据库查询结果）：

@mcp.resource("config://app_settings")
def get_app_config() -> dict:
    return {"theme": "dark", "language": "zh-CN"}

• 提示（Prompts）：定义与大模型交互的上下文模板（需结合MCP协议规范）。

@mcp.prompt()
def code_review_prompt(code: str) -> str:
    return f"请审查以下代码并指出问题：\n\n{code}"

启动与传输配置

选择传输协议：

• 本地通信：transport='stdio'（适合IDE集成）。
• 远程通信：transport='sse'（基于HTTP事件流，需部署为Web服务）。

完整示例

# 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）：

{
  "mcpServers": {
    "list_desktop_files": {
      "command": "python3",
      "args": [
        "/Users/[USER_NAME]/[YOUR_PATH]/custom_mcp.py"
      ]
    }
  }
}

• 刷新客户端后，通过自然语言指令（如“我的桌面有哪些文件”）调用工具。

可视化调试

• 使用MCP Inspector检查消息交互：

npx @modelcontextprotocol/inspector python custom_mcp.py

• 确保服务器日志输出正常，检查权限与路径限制。

使用npx运行@modelcontextprotocol/inspector，如下所示：

打开web服务，可视化调试你所开发的Tools：

---

四、高级实践与优化

1. 安全性控制
   • 限制工具访问范围（如仅允许读取特定目录）。
   • 使用Nacos等工具管理敏感配置（如API密钥加密）。
2. 集成现有API
   • 通过Nacos + Higress方案，将存量HTTP API转换为MCP协议，无需修改代码：
     • Nacos注册服务元数据，Higress网关处理协议转换。
   • 示例：将高德地图API封装为MCP Server，支持自然语言调用天气查询。
3. 动态发现与扩展
   • 利用MCP市场（如AIbase、mcp.so）发布或引用公共服务，实现工具动态加载。

---

五、常见问题与解决方案

问题类型	解决方案
工具未被客户端识别	检查@mcp.tool()装饰器及文档字符串格式，确保函数参数和返回值类型明确。
传输协议不兼容	确认客户端支持的协议类型（如SSE需配置Web服务器）。
权限不足	限制资源访问路径，使用沙箱环境运行敏感操作。

---

通过上述步骤，开发者可以快速构建一个功能完整的MCP Server，并结合生态工具实现高效集成。更多进阶实践可参考MCP官方文档及社区资源（如AIbase、GitHub示例仓库）。