MCP（模型上下文协议）服务器让 OpenClaw 代理通过标准化工具与外部服务交互。你构建一个干净的服务器，暴露类型化工具供代理可靠调用。本指南从零开始教你构建第一个 MCP 服务器。

什么是 MCP？

标准化协议

MCP 定义了 LLM 与工具通信的 JSON-RPC 协议。代理发现可用工具、理解参数、类型安全地调用。

语言无关

用 Python (FastMCP)、TypeScript (MCP SDK) 或任何支持 JSON-RPC 的语言构建。

可组合

每个 MCP 服务器处理一个领域。组合多个服务器：邮件、日历、智能家居各一个。

快速开始：Python (FastMCP)

安装 FastMCP 框架

pip install fastmcp

创建最小 MCP 服务器

# server.py
from fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_weather(city: str) -> str:
    """获取城市当前天气。"""
    return f"{city}天气: 22°C, 晴"

if __name__ == "__main__":
    mcp.run()

在 OpenClaw 配置中注册

# openclaw.config.yaml
mcp_servers:
  weather:
    command: python
    args: [server.py]

测试工具

openclaw mcp list weather get_weather --city 东京

TypeScript 替代方案

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "weather", version: "1.0.0" });
server.tool("get_weather",
  { city: z.string().describe("城市名") },
  async ({ city }) => ({
    content: [{ type: "text", text: `${city}天气: 22°C` }]
  })
);
await server.connect(new StdioServerTransport());

常见服务器模式

API 包装器

包装 REST API（GitHub、Jira、Slack）。处理认证、分页、限速。

get_issues, create_pr, send_message

数据库查询

暴露只读 SQL 查询。始终使用参数化查询。写入需审批。

query_customers, get_order_status

IoT 控制

通过 MQTT 或 HTTP 控制智能家居。包含安全约束。

set_thermostat, toggle_lights

文件处理

PDF 解析、图像分析、数据转换。返回结构化结果。

parse_invoice, extract_table

安全规则

写操作必须有显式用户审批流程
用 schema（Zod/Pydantic）验证所有输入——永远不信任 LLM 输出
API 密钥用环境变量，永远不硬编码
实现限速防止代理驱动的 API 滥用
记录所有工具调用用于审计
沙盒化文件系统访问——限制特定目录

测试你的服务器

openclaw mcp list # 列出已注册服务器

openclaw mcp list <server> <tool> # 测试特定工具

openclaw logs <server> # 查看服务器日志

npx @modelcontextprotocol/inspector # 可视化 MCP 调试器

Troubleshooting

服务器无法启动

检查 stderr：openclaw logs <name>。常见：缺少依赖或 Python 路径错误。

工具未被发现

确保工具有 docstring/描述。MCP 需要描述才能发现工具。

工具调用超时

默认超时 30 秒。在配置中增加 mcp_servers.<name>.timeout: 60。

代理错误调用工具

添加更严格的参数描述和示例。使用 Zod/Pydantic 验证。

MCP 服务器检查清单

✅ 服务器独立运行无错误

✅ 所有工具有清晰描述和类型化参数

✅ 用 Zod/Pydantic 做输入验证

✅ API 密钥在环境变量中

✅ 已实现限速

✅ 错误处理返回有用信息

✅ 已在 openclaw.config.yaml 注册

✅ 已用 openclaw mcp list 测试

什么是 MCP？

标准化协议

MCP 定义了 LLM 与工具通信的 JSON-RPC 协议。代理发现可用工具、理解参数、类型安全地调用。

语言无关

用 Python (FastMCP)、TypeScript (MCP SDK) 或任何支持 JSON-RPC 的语言构建。

可组合

每个 MCP 服务器处理一个领域。组合多个服务器：邮件、日历、智能家居各一个。

快速开始：Python (FastMCP)

安装 FastMCP 框架

pip install fastmcp

创建最小 MCP 服务器

# server.py
from fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_weather(city: str) -> str:
    """获取城市当前天气。"""
    return f"{city}天气: 22°C, 晴"

if __name__ == "__main__":
    mcp.run()

在 OpenClaw 配置中注册

# openclaw.config.yaml
mcp_servers:
  weather:
    command: python
    args: [server.py]

测试工具

openclaw mcp list weather get_weather --city 东京

TypeScript 替代方案

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "weather", version: "1.0.0" });
server.tool("get_weather",
  { city: z.string().describe("城市名") },
  async ({ city }) => ({
    content: [{ type: "text", text: `${city}天气: 22°C` }]
  })
);
await server.connect(new StdioServerTransport());

常见服务器模式

API 包装器

包装 REST API（GitHub、Jira、Slack）。处理认证、分页、限速。

get_issues, create_pr, send_message

数据库查询

暴露只读 SQL 查询。始终使用参数化查询。写入需审批。

query_customers, get_order_status

IoT 控制

通过 MQTT 或 HTTP 控制智能家居。包含安全约束。

set_thermostat, toggle_lights

文件处理

PDF 解析、图像分析、数据转换。返回结构化结果。

parse_invoice, extract_table

Troubleshooting

服务器无法启动

检查 stderr：openclaw logs <name>。常见：缺少依赖或 Python 路径错误。

工具未被发现

确保工具有 docstring/描述。MCP 需要描述才能发现工具。

工具调用超时

默认超时 30 秒。在配置中增加 mcp_servers.<name>.timeout: 60。

代理错误调用工具

添加更严格的参数描述和示例。使用 Zod/Pydantic 验证。

MCP 服务器构建指南

什么是 MCP？

标准化协议

语言无关

可组合

快速开始：Python (FastMCP)

TypeScript 替代方案

常见服务器模式

API 包装器

数据库查询

IoT 控制

文件处理

安全规则

测试你的服务器

Troubleshooting

MCP 服务器检查清单

▶ Related Resources

MCP 服务器构建指南

什么是 MCP？

标准化协议

语言无关

可组合

快速开始：Python (FastMCP)

TypeScript 替代方案

常见服务器模式

API 包装器

数据库查询

IoT 控制

文件处理

安全规则

测试你的服务器

Troubleshooting

MCP 服务器检查清单

▶ Related Resources