OpenClaw MCP Tools

Notice: OpenClaw 2026.3.22 and later have built-in native MCP support. If you are using these versions, you do not need this plugin — simply configure MCP servers via openclaw mcp set or in ~/.openclaw/openclaw.json. For OpenClaw versions prior to 2026.3.22, this plugin is recommended as it provides MCP tool bridging that is not available natively.

中文文档

Bridge MCP server tools as native OpenClaw tools. AI agents can call them directly without CLI.

Version compatibility: 2.0.0 requires OpenClaw 2026.3.22 or later (new plugin SDK). For earlier OpenClaw versions, use 1.x.

Why not the official mcporter?

OpenClaw officially supports MCP through mcporter skill, but it has limitations:

1. Indirect invocation: AI → read mcporter skill → shell command → mcporter CLI → MCP server
2. MCP tools are invisible to the agent — you must manually list them in TOOLS.md

Advantages of this plugin:

| | mcporter (official) | OpenClaw MCP Tools (this plugin) | |---|---|---| | Invocation | AI runs shell commands | AI calls native tools directly | | Latency | Spawns CLI process each time | Direct call, no overhead | | Tool descriptions | AI must learn mcporter syntax | Tool schemas are directly visible | | Dependency | Requires mcporter CLI | No extra dependencies |

In short: mcporter teaches AI to use a hammer, this plugin puts the hammer directly in AI's hand.

Features

• Connect to multiple MCP servers simultaneously
• Auto-reconnect on disconnect
• Tool name prefix (avoid conflicts)
• Tool filtering
• Supports stdio / SSE / streamableHttp transports
• CLI commands for MCP management

CLI Commands

OpenClaw MCP Tools provides CLI commands to view MCP server status:

v2.0.0 renamed the command from mcp to mcp-tools to avoid conflicts with OpenClaw's built-in mcp command. If you are using v1.x, replace mcp-tools with mcp in all commands below.

openclaw mcp-tools <command> [options]

Available Commands

| Command | Description | |---------|-------------| | list | List configured MCP servers and connection status | | tools | List available MCP tools from connected servers |

Examples

# List all configured servers
openclaw mcp-tools list

# List with JSON output
openclaw mcp-tools list --json

# List available tools
openclaw mcp-tools tools
openclaw mcp-tools tools --server github
openclaw mcp-tools tools --json

Standalone Testing

You can test CLI commands without installing into OpenClaw:

# Create config file (for standalone testing only)
cp standalone-test-config.example.json standalone-test-config.json

# Edit config as needed, then run
npx tsx src/cli.ts mcp-tools --help
npx tsx src/cli.ts mcp-tools list
npx tsx src/cli.ts mcp-tools tools

Or use environment variable:

MCP_SERVERS='[{"name":"test","type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/tmp"]}]' \
npx tsx src/cli.ts mcp-tools list

Installation

# Local link
openclaw plugins install -l ./openclaw-mcp-tools

# Or via npm
openclaw plugins install openclaw-mcp-tools

Configuration

Add to your OpenClaw config file (~/.openclaw/openclaw.json):

stdio transport (local process)

{
  "plugins": {
    "entries": {
      "openclaw-mcp-tools": {
        "enabled": true,
        "config": {
          "servers": [
            {
              "name": "github",
              "type": "stdio",
              "command": "npx",
              "args": ["-y", "@modelcontextprotocol/server-github"],
              "env": { "GITHUB_TOKEN": "ghp_xxx" }
            }
          ]
        }
      }
    }
  }
}

streamableHttp transport (remote server)

{
  "plugins": {
    "entries": {
      "openclaw-mcp-tools": {
        "enabled": true,
        "config": {
          "servers": [
            {
              "name": "remote",
              "type": "streamableHttp",
              "url": "http://localhost:3000/mcp",
              "headers": { "Authorization": "Bearer xxx" }
            }
          ]
        }
      }
    }
  }
}

Server configuration

Config path: plugins.entries.openclaw-mcp-tools.config.servers[]

| Field | Required | Transport | Description | |-------|----------|-----------|-------------| | name | Yes | All | Unique server identifier | | type | Yes | All | stdio / sse / streamableHttp | | enabled | No | All | Enable/disable, default true | | toolPrefix | No | All | Tool name prefix, e.g. web_ | | toolFilter | No | All | Only load specified tools (array) | | command | Yes* | stdio | Command to run, e.g. npx | | args | No | stdio | Command arguments (array) | | env | No | stdio | Environment variables, e.g. { "GITHUB_TOKEN": "ghp_xxx" } | | url | Yes* | sse / streamableHttp | Server URL | | headers | No | streamableHttp | HTTP request headers, e.g. { "Authorization": "Bearer xxx" } |

*command is required for stdio transport; url is required for sse / streamableHttp transport.

Global configuration

Config path: plugins.entries.openclaw-mcp-tools.config

| Field | Default | Description | |-------|---------|-------------| | autoReconnect | true | Auto-reconnect on disconnect | | reconnectDelayMs | 5000 | Reconnect delay (ms) | | toolCallTimeoutMs | 60000 | Tool call timeout (ms) |

Performance Tips

Too many tools may degrade model performance. Each MCP server can expose dozens of tools, and the model must process all tool schemas on every request. Consider:

1. Use toolFilter to only load the tools you need from an MCP server:

   { "name": "github", "toolFilter": ["search_repositories", "get_issue"], ... }

2. Use enabled: false to temporarily disable a server without deleting config

3. Block tools in OpenClaw config - Add tool names to tools.deny array in your OpenClaw configuration:

   "tools": {
     "deny": ["mcp_tool_name_to_block", "another_tool"]
   }

Troubleshooting

Tool call timeout

When an MCP tool takes a long time to respond (e.g., image recognition), it may exceed the default 60s timeout. Increase it in the global config:

"plugins": {
  "entries": {
    "openclaw-mcp-tools": {
      "config": {
        "toolCallTimeoutMs": 120000
      }
    }
  }
}

Note: OpenClaw itself may also have a tool call timeout. If so, you need to increase both.

Tool name conflicts

When multiple MCP servers expose tools with the same name, the plugin automatically renames the later one to serverName.toolName (e.g., github.web-search) to avoid conflicts. You can also use toolPrefix to manually prevent conflicts:

{
  "servers": [
    { "name": "server-a", "toolPrefix": "a_", ... },
    { "name": "server-b", "toolPrefix": "b_", ... }
  ]
}

Other issues

| Issue | Solution | |-------|----------| | Connection failed | Check command path and environment variables | | Tools not registered | Check toolFilter configuration | | Environment variables not working | env values must be strings |

Development

npm install && npm run build

MIT License