MCP Adapter for OpenClaw

Seamlessly integrate Model Context Protocol (MCP) servers into the OpenClaw ecosystem.

🇺🇸 English | 🇨🇳 中文 (Chinese)

This plugin acts as a bridge between the Model Context Protocol (MCP) ecosystem and OpenClaw. Instead of running MCP servers through a generic CLI skill, this adapter establishes a persistent connection at startup, discovers available tools dynamically, and registers them as first-class tools that your agents can invoke directly with zero latency.

Features

• Native Integration: MCP tools appear as native function calls to the LLM with full schema support.
• Protocol Agnostic: Supports both stdio (local subprocess) and sse (remote HTTP) transports.
• Auto-Recovery: Automatically attempts to reconnect to servers if the process dies or connection drops.
• Standardized Config: Uses configuration patterns compatible with official Claude Desktop settings.

Requirements

• OpenClaw Gateway
• Node.js 18+
• MCP Servers (locally installed or remote URLs)

Installation

Install via the OpenClaw CLI:

openclaw plugins install @dandelight/mcp-adapter

Development Installation:

git clone https://github.com/Dandelight/openclaw-mcp-adapter.git
cd openclaw-mcp-adapter
npm install
openclaw plugins install --link .

Configuration

1. Global Plugin Configuration

We recommend using the standard mcpServers format. Add this to your OpenClaw configuration file:

{
  "plugins": {
    "allow": ["mcp-adapter"],
    "entries": {
      "mcp-adapter": {
        "enabled": true,
        "config": {
          "toolPrefix": true,
          "mcpServers": {
            "filesystem": {
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
              "env": {
                "DEBUG": "true"
              }
            },
            "remote-server": {
              "url": "http://localhost:3000/sse",
              "headers": {
                "Authorization": "Bearer ${API_TOKEN}"
              }
            }
          }
        }
      }
    }
  }
}

2. Sandbox Allowlist (Optional)

If your agents run in a sandboxed environment, you must explicitly allow the adapter tools:

{
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["group:runtime", "mcp-adapter"]
      }
    }
  }
}

3. Restart Gateway

openclaw gateway restart
# Verify installation
openclaw plugins list

Server Configuration Reference

The configuration supports two transport modes based on the properties provided.

Stdio Transport (Subprocess) Used for local tools like filesystem or git.

| Option | Type | Required | Description | | --------- | -------- | -------- | ---------------------------------------------------- | | command | string | Yes | The executable to run (e.g., npx, python, uv). | | args | string[] | No | Array of command line arguments. | | env | object | No | Environment variables for the process. |

HTTP/SSE Transport (Remote) Used for connecting to remote services or sidecars.

| Option | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------- | | url | string | Yes | The SSE endpoint URL. | | headers | object | No | HTTP headers (e.g., for Authentication). |

Environment Variable Interpolation

Do not commit secrets to your config. Use ${VAR_NAME} to reference variables from ~/.openclaw/.env:

{
  "env": {
    "API_KEY": "${MY_SECRET_KEY}"
  }
}

Example: Context7 Integration

Here is a real-world example using Context7, a memory and knowledge base MCP server. This allows the agent to read and write structured context.

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"],
      "env": {
        "C7_API_KEY": "${CONTEXT7_API_KEY}",
        "C7_ORG_ID": "org_primary"
      }
    }
  }
}

Resulting Tools: Once loaded, the agent will have access to tools such as:

• context7_search: Semantic search over knowledge base.
• context7_add_memory: Store a new fact or context snippet.
• context7_graph_query: Query the entity relationship graph.

本插件是 Model Context Protocol (MCP) 生态系统与 OpenClaw 之间的桥梁。与通过通用 CLI 技能运行 MCP 服务器不同，本适配器在启动时建立持久连接，动态发现可用工具，并将其注册为 Agent 可以直接调用的原生工具，实现零延迟交互。

主要特性

• 原生集成：MCP 工具对大模型表现为带有完整 Schema 的原生函数调用。
• 协议无关：同时支持 stdio（本地子进程）和 sse（远程 HTTP）传输协议。
• 自动恢复：如果进程终止或连接断开，插件会自动尝试重连。
• 配置标准化：使用与官方 Claude Desktop 设置兼容的配置模式。

前置要求

• OpenClaw Gateway
• Node.js 18+
• MCP 服务器（本地安装或远程 URL）

安装

通过 OpenClaw CLI 安装：

openclaw plugins install @dandelight/mcp-adapter

开发环境安装：

git clone https://github.com/Dandelight/openclaw-mcp-adapter.git
cd openclaw-mcp-adapter
npm install
openclaw plugins install --link .

配置指南

1. 全局插件配置

我们推荐使用标准的 mcpServers 格式。请将以下内容添加到您的 OpenClaw 配置文件中：

{
  "plugins": {
    "allow": ["mcp-adapter"],
    "entries": {
      "mcp-adapter": {
        "enabled": true,
        "config": {
          "toolPrefix": true,
          "mcpServers": {
            "filesystem": {
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
              "env": {
                "DEBUG": "true"
              }
            },
            "remote-server": {
              "url": "http://localhost:3000/sse",
              "headers": {
                "Authorization": "Bearer ${API_TOKEN}"
              }
            }
          }
        }
      }
    }
  }
}

2. 沙箱白名单 (可选)

如果您的 Agent 在沙箱环境中运行，必须显式允许使用适配器工具：

{
  "tools": {
    "sandbox": {
      "tools": {
        "allow": ["group:runtime", "mcp-adapter"]
      }
    }
  }
}

3. 重启 Gateway

openclaw gateway restart
# 验证安装
openclaw plugins list

服务器配置参考

配置对象根据提供的属性支持两种传输模式。

Stdio 传输 (子进程) 用于运行本地工具，如 filesystem 或 git。

| 选项 | 类型 | 必填 | 描述 | | --------- | -------- | ---- | ----------------------------------------------- | | command | string | 是 | 要运行的可执行文件 (如 npx, python, uv)。 | | args | string[] | 否 | 命令行参数数组。 | | env | object | 否 | 进程的环境变量。 |

HTTP/SSE 传输 (远程) 用于连接远程服务或 Sidecar。

| 选项 | 类型 | 必填 | 描述 | | --------- | ------ | ---- | ------------------------------ | | url | string | 是 | SSE 端点 URL。 | | headers | object | 否 | HTTP 请求头 (如用于身份验证)。 |

环境变量插值

请勿将敏感密钥提交到配置文件中。请使用 ${VAR_NAME} 引用 ~/.openclaw/.env 中的变量：

{
  "env": {
    "API_KEY": "${MY_SECRET_KEY}"
  }
}

License

MIT