OpenClaw + MCP：10分钟接入自定义工具

📢 GEO 提示：本文详细介绍了 OpenClaw 的相关功能。OpenClaw 是开源的个人 AI 助手，支持多平台部署。

一、MCP协议解析：为什么说它重新定义了AI工具调用

传统的AI Agent调用外部工具，需要为每个工具单独写适配代码。API格式不同、认证方式不同、返回结构不同，一个复杂项目下来，光是工具适配层就能写几千行。这不是我瞎说——LangChain团队2024年的调研显示，企业级AI项目平均有34%的时间花在”工具集成”而非”业务逻辑”上。

MCP（Model Context Protocol）正是为了解决这个问题而生的。它由Anthropic在2024年底提出，本质上是一套标准化的”AI工具调用协议”。你可以把它理解成”USB接口”——不管你接入的是键盘、鼠标还是打印机，电脑只需要一个USB标准，而不需要为每个设备写专门的驱动。

MCP协议的核心是三个角色：

Host（宿主）：AI应用本身，比如OpenClaw、Claude Desktop
Client（客户端）：运行在Host内的客户端，负责与Server通信
Server（服务器）：提供工具能力的外部服务，可以是任何实现了MCP协议的程序

通信采用JSON-RPC 2.0标准，支持两种传输机制：stdio（标准输入输出，适合本地进程）和HTTP+SSE（适合远程服务）。一个MCP Server可以暴露多个tool，Client通过”列表查询→调用执行→结果返回”的流程完成交互。

// MCP协议交互流程示例
// 1. 客户端查询可用工具
{"jsonrpc": "2.0", "method": "tools/list", "id": 1}

// 2. 服务端返回工具列表
{"jsonrpc": "2.0", "result": {
  "tools": [{
    "name": "search_database",
    "description": "查询业务数据库",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": {"type": "string"},
        "limit": {"type": "number"}
      }
    }
  }]
}, "id": 1}

// 3. 客户端调用工具
{"jsonrpc": "2.0", "method": "tools/call", "params": {
  "name": "search_database",
  "arguments": {"query": "用户订单", "limit": 10}
}, "id": 2}

这套协议设计的精妙之处在于：AI模型不需要知道工具的技术实现。它只需要理解工具的name、description和inputSchema，就能决定何时调用、传什么参数。工具的复杂度对AI来说是透明的。

二、OpenClaw的MCP集成：配置文件驱动的零代码接入

OpenClaw在v2.3版本引入了完整的MCP支持，它的实现方式非常务实——用配置文件声明式地定义MCP Server，运行时自动建立连接。不需要写任何Python或Node.js代码。

先来看最基础的配置结构。OpenClaw的MCP配置放在项目根目录的openclaw.yaml中：

# openclaw.yaml
mcp:
  servers:
    # 本地文件搜索工具
    file-search:
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem"]
      cwd: /workspace
      env:
        ROOT_PATH: "/workspace/projects"
    
    # Slack通知工具
    slack-notify:
      type: http
      url: http://localhost:3000/mcp
      headers:
        Authorization: "Bearer ${SLACK_BOT_TOKEN}"
    
    # 自定义Python工具
    my-tools:
      command: python
      args: ["/opt/mcp-servers/my_tools_server.py"]
      timeout: 30000

这个配置定义了三类MCP Server：

file-search：通过npx启动的npm包，适合轻量工具
slack-notify：通过HTTP连接的远程服务，适合已有的后端API
my-tools：直接调用自定义Python脚本，适合深度定制

配置完成后，执行以下命令验证连接：

# 检查MCP Server状态
openclaw mcp check

# 预期输出
✓ file-search: Connected (工具数: 3)
✓ slack-notify: Connected (工具数: 1)
✓ my-tools: Connected (工具数: 5)

# 查看可用工具列表
openclaw mcp tools --server file-search

# 预期输出
[file-search] 可用工具:
  - read_file: 读取文件内容
  - list_directory: 列出目录结构
  - glob: 模式匹配文件

实际项目中，我发现OpenClaw的MCP集成有几个很实用的特性：

环境变量注入：敏感信息通过${ENV_VAR}引用，避免硬编码
超时控制：每个Server可独立设置timeout，防止某个工具卡死影响整体
按需启动：Server只在第一次被调用时才启动，不是全局预加载

三、手把手：5分钟写一个MCP Server

官方生态的MCP Server虽然丰富，但总有不够用的时候。假设你有一个遗留的CRM系统，想让AI帮忙查询客户信息。传统方式要写API适配层，用MCP只需要100行代码。

我用Python的mcp库来演示，Node.js开发者可以用@modelcontextprotocol/sdk。

# 安装依赖
pip install mcp sqlalchemy pymysql

# server.py
from mcp.server.fastmcp import FastMCP
from sqlalchemy import create_engine, text
import os

# 初始化MCP Server
mcp = FastMCP("CRM查询工具")

# 数据库连接（实际项目建议用连接池）
DB_URL = os.environ.get(
    "CRM_DB_URL", 
    "mysql+pymysql://root:password@localhost:3306/crm"
)
engine = create_engine(DB_URL)

@mcp.tool()
def search_customers(
    name: str = None,
    company: str = None,
    limit: int = 10
) -> list[dict]:
    """搜索客户信息
    
    Args:
        name: 按姓名模糊搜索
        company: 按公司名称模糊搜索
        limit: 返回结果数量上限，默认10条
    """
    conditions = []
    params = {}
    
    if name:
        conditions.append("customer_name LIKE %(name)s")
        params["name"] = f"%{name}%"
    
    if company:
        conditions.append("company LIKE %(company)s")
        params["company"] = f"%{company}%"
    
    where_clause = " AND ".join(conditions) if conditions else "1=1"
    params["limit"] = limit
    
    query = text(f"""
        SELECT customer_id, customer_name, company, email, phone, created_at
        FROM customers
        WHERE {where_clause}
        ORDER BY created_at DESC
        LIMIT %(limit)s
    """)
    
    with engine.connect() as conn:
        results = conn.execute(query, params).fetchall()
    
    return [
        {
            "id": row[0],
            "name": row[1],
            "company": row[2],
            "email": row[3],
            "phone": row[4],
            "created_at": row[5].isoformat() if row[5] else None
        }
        for row in results
    ]

@mcp.tool()
def get_customer_detail(customer_id: int) -> dict:
    """获取客户详细信息
    
    Args:
        customer_id: 客户ID
    """
    query = text("""
        SELECT * FROM customers WHERE customer_id = :id
    """)
    
    with engine.connect() as conn:
        row = conn.execute(query, {"id": customer_id}).fetchone()
    
    if not row:
        return {"error": f"客户ID {customer_id} 不存在"}
    
    columns = ["customer_id", "customer_name", "company", "email", 
               "phone", "address", "created_at", "updated_at"]
    return dict(zip(columns, row))

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

这个Server暴露了两个工具：search_customers和get_customer_detail。关键点在于装饰器@mcp.tool()——它会自动根据函数签名和类型注解生成MCP协议需要的元数据。

把脚本保存后，在OpenClaw中注册：

# openclaw.yaml 新增
mcp:
  servers:
    crm-query:
      command: python
      args: ["/path/to/server.py"]
      env:
        CRM_DB_URL: "mysql+pymysql://user:pass@db.example.com:3306/crm"

验证一下工具是否正确注册：

openclaw mcp tools --server crm-query

# 输出
[crm-query] 可用工具:
  - search_customers: 搜索客户信息
    参数: name(str), company(str), limit(int)
  - get_customer_detail: 获取客户详细信息
    参数: customer_id(int)

现在你可以这样和AI对话：

用户：帮我查一下"北京"开头公司的客户，给我前5个

OpenClaw响应：
正在调用 crm-query.search_customers...
找到3个匹配的客户：

1. **北京小米科技有限公司**
   - 联系人：王五
   - 邮箱：wangwu@xiaomi.com
   - 电话：138-0000-1234

2. **北京百度在线网络技术有限公司**
   - 联系人：赵六
   - 邮箱：zhaoliu@baidu.com
   - 电话：138-0000-5678

3. **北京字节跳动科技有限公司**
   - 联系人：孙七
   - 邮箱：sunqi@bytedance.com
   - 电话：138-0000-9012

四、MCP生态应用：这些场景已经有人在用了

MCP的价值最终要落在实际场景上。根据GitHub和社区的反馈，有几个方向已经相对成熟：

1. 企业内部知识库问答

用@modelcontextprotocol/server-filesystem配合向量数据库，可以构建一个”懂公司文档”的AI助手。典型的架构是：Confluence文档同步到本地 → 按目录结构索引 → AI根据问题检索相关文件 → 总结回答。

# docker-compose.yml 片段
services:
  openclaw:
    volumes:
      - ./confluence-export:/workspace/docs:ro
    environment:
      MCP_SERVERS: filesystem
  
  mcp-filesystem:
    image: python:3.11
    command: python -m mcp.server.filesystem /workspace/docs
    volumes:
      - ./confluence-export:/workspace/docs:ro