自建MCP服务器：让OpenClaw调用你的私有API

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

MCP协议解析：AI与外部世界对话的”通用翻译器”

MCP（Model Context Protocol）本质上是一套标准化的通信协议，解决的核心问题是：让AI模型能够可靠地调用外部工具和数据源。以往每接入一个新工具，开发者都要写一套定制化代码——这就像每买一个电器就要重新布一套电线。MCP则相当于统一的”插座标准”，只要工具端实现了MCP Server，AI端就能即插即用。

MCP的三角架构

MCP采用经典的Client-Server模式，但参与者有三个：

Host：运行AI应用的容器（如OpenClaw），负责整体调度
Client：嵌入在Host内部，与Server保持长连接
Server：暴露具体能力的轻量进程，类比”工具说明书”

数据传输走两种模式：stdio（标准输入输出，适合本地进程）和SSE（Server-Sent Events，适合远程服务）。自建MCP服务器时，stdio模式配置最简单，适合个人开发者快速验证。

为什么选择MCP而非直接API调用

直接调用的痛在于：AI不知道你的API能做什么、参数怎么填、返回什么格式。MCP Server在初始化时会向AI暴露工具清单（tools）和资源列表（resources），相当于自带说明书。AI不再需要”猜”——它能明确知道：”查询库存”需要传product_id，返回值是JSON格式的库存数量。

OpenClaw接入MCP后，会在对话上下文自动注入可用工具列表。这意味着你不需要写复杂的Prompt工程，AI自然知道何时调用你的私有接口。

OpenClaw MCP集成：从配置到调用的完整链路

配置文件结构

OpenClaw通过~/.openclaw/mcp.json管理所有MCP连接。配置采用JSON Schema，核心字段包括：

{
  "mcpServers": {
    "my-inventory": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/inventory-server/index.js"],
      "env": {
        "API_KEY": "your-secret-key"
      }
    },
    "remote-service": {
      "type": "sse",
      "url": "https://api.example.com/mcp"
    }
  }
}

关键点：env字段用于传递敏感信息，不会出现在对话日志中。type决定通信方式——本地工具用stdio避免网络开销，需要远程复用时切换SSE。

连接验证的实操步骤

配置完成后，验证连接是否正常：

重启OpenClaw客户端
打开开发者工具（DevTools），切换到”Console”标签
输入测试命令：/mcp list

正常返回会列出已加载的Server名称和可用工具数量。如果报错，重点检查：Node.js版本（需v18+）、路径是否正确、env变量是否已设置。

调用日志的查看方法

OpenClaw会记录每次MCP调用的请求和响应。日志路径在~/.openclaw/logs/mcp-debug.log。生产环境建议开启debug: true配置项，便于排查”AI明明说了要调用但没调用”的问题——通常是因为返回值格式不符合预期。

手把手搭建：让Notion API成为MCP工具

场景选择理由

Notion没有官方MCP支持，但它的API能力完整。这个场景典型在于：你要封装一个”有API但AI不知道如何使用”的数据源。完成后，OpenClaw可以直接回答”本周新增了多少待办事项”这类问题。

项目初始化

mkdir notion-mcp-server && cd notion-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk @notionhq/client dotenv

@modelcontextprotocol/sdk是官方提供的Server开发框架，封装了协议细节，你只需关注业务逻辑。@notionhq/client是Notion官方的SDK。

Server核心代码

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { Client } from "@notionhq/client";

const notion = new Client({ auth: process.env.NOTION_TOKEN });

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

// 声明AI可调用的工具
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "query_database",
        description: "查询Notion数据库中的条目",
        inputSchema: {
          type: "object",
          properties: {
            database_id: { type: "string", description: "数据库ID" },
            filter: { type: "string", description: "过滤条件（可选）" }
          },
          required: ["database_id"]
        }
      },
      {
        name: "create_page",
        description: "在指定数据库创建新页面",
        inputSchema: {
          type: "object",
          properties: {
            parent_id: { type: "string", description: "父页面或数据库ID" },
            title: { type: "string", description: "页面标题" },
            content: { type: "string", description: "页面内容" }
          },
          required: ["parent_id", "title"]
        }
      }
    ]
  };
});

// 处理工具调用
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    if (name === "query_database") {
      const response = await notion.databases.query({
        database_id: args.database_id,
        filter: args.filter ? JSON.parse(args.filter) : undefined
      });
      return { content: [{ type: "text", text: JSON.stringify(response.results) }] };
    }
    
    if (name === "create_page") {
      const response = await notion.pages.create({
        parent: { database_id: args.parent_id },
        properties: {
          title: { title: [{ text: { content: args.title } }] }
        }
      });
      return { content: [{ type: "text", text: `Created: ${response.id}` }] };
    }
  } catch (error) {
    return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
  }
});

// 启动
const transport = new StdioServerTransport();
server.connect(transport);

这段代码的核心逻辑：ListToolsRequestSchema告诉AI有哪些工具可用（类型、参数说明），CallToolRequestSchema处理实际调用。inputSchema的描述要足够清晰——AI会依赖这些描述决定何时调用、怎么填参数。

环境配置与启动

# .env文件
NOTION_TOKEN=secret_xxxxxxxxxxxxx

# OpenClaw配置添加
# 在 ~/.openclaw/mcp.json 中加入：
{
  "mcpServers": {
    "notion": {
      "type": "stdio",
      "command": "node",
      "args": ["/绝对路径/notion-mcp-server/dist/index.js"],
      "env": {
        "NOTION_TOKEN": "secret_xxxxxxxxxxxxx"
      }
    }
  }
}

# 测试运行
node dist/index.js

执行后，OpenClaw会启动子进程并建立stdio连接。首次连接时，Server会打印”Server connected”，表示协议握手成功。

对话测试

在OpenClaw中尝试：

用户：帮我查询数据库 db_abc123 中，所有状态为"进行中"的任务

OpenClaw（调用query_database）:
{
  "database_id": "db_abc123",
  "filter": '{"property":"状态","select":{"equals":"进行中"}}'
}

OpenClaw返回：查询到3条任务
1. [任务名] - 负责人：张三 - 截止：6月20日
2. ...

注意看：AI自动将”状态为进行中”翻译成了Notion的filter语法。这是MCP的价值——你只需要描述业务需求，AI负责翻译成正确的API调用。

生态应用：MCP Server的进阶玩法

社区已有的成熟方案

MCP生态正在快速扩张，不必从零造轮子。主流方向包括：

数据源连接：GitHub、Slack、Notion（上述案例）、Google Drive
开发辅助：Filesystem（安全读写本地文件）、Brave Search（实时搜索）
AI to AI通信：用MCP Server暴露另一个AI的能力，形成工具链

GitHub MCP Server是另一个高频场景。配置后，AI可以帮你总结PR改动、查询CI状态、甚至提交代码。这对Code Review场景特别有价值——你不需要在多个窗口切换。

安全边界的设计原则

MCP能力越强，安全风险越高。生产环境建议：

最小权限：MCP Server运行的Token应该是功能所需的最小范围，不建议用管理员Token
调用审计：在Server层记录每次调用的发起者、时间和参数，存入审计日志
参数校验：不信任AI传入的参数，在Server层做二次校验，防止Prompt注入

对于高敏感操作（如删除数据），建议增加确认机制——Server返回”待确认”状态，让用户明确授权后再执行。

多Server编排技巧

OpenClaw支持同时加载多个MCP Server。复杂场景下，可以设计”聚合Server”：用一个入口暴露多个子工具，内部路由到不同的专业Server。这样做的好处是减少OpenClaw配置复杂度，同时在聚合层统一处理认证和限流。

例如：一个”企业助手”Server，内部路由到Notion（文档）、Jira（任务）、Confluence（知识库）三个数据源。AI调用”查询项目文档”时，聚合Server自动判断走Confluence路径，返回格式统一处理。

总结

MCP协议正在成为AI应用与外部工具交互的事实标准。通过OpenClaw的MCP集成，你可以将任何有API的数据源变成AI可调用的工具。关键路径是：理解协议架构→编写符合Schema的Server→在OpenClaw配置连接→对话中自然调用。上手门槛不高，但深度使用需要关注安全边界和Server质量。

整理自 OpenClaw 官方文档 | 2026年06月17日