OpenClaw MCP Server配置和使用教程

前言

MCP（Model Context Protocol，模型上下文协议）是一个开放标准，它定义了 AI 模型与外部工具和数据源之间的通信方式。OpenClaw 深度集成了 MCP，让 AI 助手能够通过 MCP Server 与文件系统、数据库、API 等外部资源交互。

本教程将从概念出发，带你掌握 MCP 在 OpenClaw 中的配置和使用。

什么是 MCP

核心概念

MCP 解决的核心问题是：让 AI 模型能够安全、标准化地使用外部工具。

用户消息 → OpenClaw → AI 模型 → 需要工具 → MCP Client → MCP Server → 执行操作
                                                                ↓
用户收到回复 ← OpenClaw ← AI 模型 ← 获取结果 ← MCP Client ← MCP Server

MCP 的三个核心能力

MCP Server 类型

MCP Server 有两种运行方式：

• Stdio（标准输入输出）：作为子进程运行，通过 stdin/stdout 通信
• SSE（Server-Sent Events）：作为 HTTP 服务运行，通过 HTTP 通信

在 OpenClaw 中配置 MCP Server

基本配置结构

在 ~/.config/openclaw/openclaw.json5 中配置 MCP：

{
  mcp: {
    servers: {
      // 每个 MCP Server 有一个唯一的名称
      "server-name": {
        // Stdio 模式的配置
        command: "npx",
        args: ["-y", "@package/mcp-server"],
        env: {
          // 环境变量
          API_KEY: "your-key"
        }
      },

      // 或者 SSE 模式的配置
      "remote-server": {
        url: "http://localhost:3001/sse",
        headers: {
          "Authorization": "Bearer your-token"
        }
      }
    }
  }
}

多 Server 并存

你可以同时配置多个 MCP Server：

{
  mcp: {
    servers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem",
               "--allow-read", "--allow-write", "/home/user/documents"]
      },
      "database": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-sqlite",
               "--db-path", "/home/user/data/app.db"]
      },
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"]
      },
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxx"
        }
      }
    }
  }
}

常用 MCP Server 详解

1. 文件系统 MCP Server

让 AI 能读写本地文件，适合文档管理、数据存储等场景。

{
  mcp: {
    servers: {
      "filesystem": {
        command: "npx",
        args: [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "--allow-read",      // 允许读取
          "--allow-write",     // 允许写入
          "/home/user/docs"    // 限定目录范围
        ]
      }
    }
  }
}

提供的工具：

安全提示：务必通过路径参数限制可访问的目录范围，避免给予整个文件系统的访问权限。

2. SQLite 数据库 MCP Server

让 AI 能查询和操作 SQLite 数据库。

{
  mcp: {
    servers: {
      "sqlite": {
        command: "npx",
        args: [
          "-y",
          "@modelcontextprotocol/server-sqlite",
          "--db-path", "/home/user/data/myapp.db"
        ]
      }
    }
  }
}

提供的工具：

使用示例——用户在聊天中说"查一下上周的销售数据"，AI 会自动通过 MCP 工具执行 SQL 查询并返回结果。

3. HTTP Fetch MCP Server

让 AI 能发起 HTTP 请求，调用任意 REST API。

{
  mcp: {
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        env: {
          // 可选：配置默认请求头
          DEFAULT_HEADERS: '{"User-Agent": "OpenClaw/1.0"}'
        }
      }
    }
  }
}

提供的工具：

4. GitHub MCP Server

与 GitHub 仓库交互，查看 Issue、PR、代码等。

{
  mcp: {
    servers: {
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxx"
        }
      }
    }
  }
}

提供的工具：

5. PostgreSQL MCP Server

连接 PostgreSQL 数据库：

{
  mcp: {
    servers: {
      "postgres": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-postgres"],
        env: {
          DATABASE_URL: "postgresql://user:pass@localhost:5432/mydb"
        }
      }
    }
  }
}

MCP 与 Skill 的协作

MCP Server 为 Skill 提供了与外部世界交互的能力。在 SKILL.md 中声明需要的 MCP 工具：

---
name: my-skill
mcp_tools:
  - filesystem    # 使用文件系统工具
  - http_fetch    # 使用 HTTP 请求工具
  - sqlite        # 使用数据库工具
---

AI 在执行 Skill 时，会根据需要自动调用对应的 MCP 工具。

实际流程示例

用户发送："帮我把上周的订单数据导出为 CSV 文件"

1. AI 识别任务需要 sqlite 和 filesystem 两个 MCP Server
2. 调用 sqlite.read_query 查询上周订单数据
3. 将查询结果格式化为 CSV
4. 调用 filesystem.write_file 保存 CSV 文件
5. 返回文件路径给用户

自定义 MCP Server

如果现有的 MCP Server 不能满足需求，你可以开发自己的。

最小化示例（Node.js）

// my-mcp-server.js
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-custom-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// 注册工具
server.setRequestHandler("tools/list", async () => ({
  tools: [{
    name: "greet",
    description: "Generate a greeting message",
    inputSchema: {
      type: "object",
      properties: {
        name: { type: "string", description: "Name to greet" }
      },
      required: ["name"]
    }
  }]
}));

// 处理工具调用
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "greet") {
    const name = request.params.arguments.name;
    return {
      content: [{ type: "text", text: `Hello, ${name}!` }]
    };
  }
});

// 启动服务器
const transport = new StdioServerTransport();
await server.connect(transport);

在 OpenClaw 中配置：

{
  mcp: {
    servers: {
      "my-custom": {
        command: "node",
        args: ["/path/to/my-mcp-server.js"]
      }
    }
  }
}

调试 MCP Server

查看 MCP 工具列表

# 查看所有已加载的 MCP 工具
openclaw doctor

输出中会列出所有已连接的 MCP Server 及其提供的工具。

启用 MCP 调试日志

# 查看 MCP 通信详情
openclaw logs --level debug

日志中会显示 MCP 工具调用的请求和响应：

[DEBUG] MCP tool call: filesystem.read_file({path: "/home/user/notes.txt"})
[DEBUG] MCP tool result: {content: [{type: "text", text: "file contents..."}]}

独立测试 MCP Server

你可以使用 MCP Inspector 工具独立测试 MCP Server：

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem --allow-read /tmp

这会打开一个 Web 界面，让你直接调用和测试 MCP 工具。

安全最佳实践

最小权限原则

{
  mcp: {
    servers: {
      "filesystem": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem",
               "--allow-read",           // 只读
               "/home/user/public-docs"  // 限定目录
        ]
        // 注意：不添加 --allow-write
      }
    }
  }
}

API 密钥安全

不要在配置文件中硬编码 API 密钥，使用环境变量：

{
  mcp: {
    servers: {
      "github": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: {
          // 引用系统环境变量
          GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

然后在系统中设置环境变量：

export GITHUB_TOKEN="ghp_xxxxx"

网络隔离

对于远程 MCP Server（SSE 模式），建议：

• 使用 HTTPS 连接
• 配置认证 Token
• 限制可访问的 IP 范围

常见问题

MCP Server 启动失败

# 检查 npx 是否能正常运行
npx -y @modelcontextprotocol/server-filesystem --help

# 检查 Node.js 版本
node --version  # 需要 22+

工具调用超时

某些 MCP 工具（如 HTTP 请求）可能因为网络原因超时。可以在配置中设置超时时间：

{
  mcp: {
    // 全局超时设置（毫秒）
    timeout: 30000,
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        // 单独设置此 Server 的超时
        timeout: 60000
      }
    }
  }
}

AI 不调用预期的工具

确认 Skill 中正确声明了 mcp_tools，并且 MCP Server 名称与配置中一致。查看调试日志确认工具是否被正确加载。

小结

MCP 是 OpenClaw 能力扩展的基石。通过配置不同的 MCP Server，你可以让 AI 助手访问文件系统、查询数据库、调用 API、操作 GitHub 等几乎任何外部资源。理解 MCP 的工作原理和配置方法，将帮助你构建更强大的 Skill 和自动化工作流。