MCP Server

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

添加到项目的 .mcp.json：

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Cursor

添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目级）：

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Windsurf

添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "clawbutler": {
      "command": "uvx",
      "args": ["clawbutler-mcp"],
      "env": {
        "CLAWBUTLER_API_URL": "https://your-instance.clawbutler.cc",
        "CLAWBUTLER_TOKEN": "your-token"
      }
    }
  }
}

Streamable HTTP（远程部署）

容器化或远程部署时，使用 HTTP 传输模式：

clawbutler-mcp --transport http --port 8080

Agent 管理（7 个工具）

list_agents, get_agent, get_agent_governance_view, enable_agent, disable_agent, set_agent_lifecycle, get_agent_config

包含 Agent 操作、生命周期切换、治理摘要和配置查看。

成本与预算（4 个工具）

get_cost_summary, get_cost_by_agent, get_cost_trend, list_budgets

支持日期范围成本追踪、按 Agent 拆分、趋势分析和预算监控。

配置安全（5 个工具）

list_config_snapshots, take_config_snapshot, diff_config_snapshots, preview_rollback, execute_rollback

配置安全能力，包含浏览快照、手动保存点、语义 diff、dry-run 回滚和正式回滚。

审计与活动（3 个工具）

search_audit_events, get_audit_event, get_recent_activity

提供多维筛选的审计搜索和最近活动流，适合调查取证。

连接器（4 个工具）

list_connectors, get_connector_detail, test_connector, diagnose_connector

网关连接器管理，支持列表、详情、连通性测试与诊断。

智能分析（4 个工具）

get_root_cause_analysis, get_reliability_scores, get_agent_reliability, get_value_comparison

智能分析面，覆盖根因分析、可靠性评分和价值对比。

运维操作（6 个工具）

get_killswitch_status, activate_killswitch, deactivate_killswitch, check_health, get_trust_status, get_dashboard

运维操作面，覆盖 Kill Switch、健康检查、信任状态与仪表盘摘要。

Runbook 自动化（4 个工具）

list_runbooks, get_runbook, execute_runbook, get_runbook_run

Runbook 自动化能力，支持浏览、带参数执行以及单次运行追踪。

治理预览（4 个工具）

preview_policy_decision, get_runtime_host_card, preview_task_grant, record_governance_evidence

预览策略与 task grant 判定、复用稳定 RuntimeHostCard，并在不开放更大写面的前提下补治理证据。

运行时主机（9 个工具）

list_runtime_hosts, get_runtime_host_detail, get_runtime_host_governance_view, discover_runtime_host, batch_add_runtime_host_instances, sync_runtime_host_sessions, get_runtime_host_managed_state, list_runtime_host_managed_sessions, list_runtime_host_managed_permissions

对已配对机器做 Hermes / Claude Code / Codex / OpenClaw 发现、治理预览、批量接入连接器、同步 attach-mode 会话，并查看托管状态 / 会话 / 待审批请求。

晨间运维检查

让 AI 助手为你做一个 Agent 舰队的晨间简报。

"检查一下我的 ClawButler 仪表盘 — 多少 Agent 在线，
今天的成本是多少，有没有待审批的？"

成本追查

不离开编辑器，直接深入分析成本异常。

"显示最近 7 天按 Agent 的成本明细。
哪个 Agent 花费最高？"

应急响应

AI 辅助的事故响应 — Kill Switch 加审计追踪。

"Agent coordinator 行为异常。
检查它的健康状态，然后激活 Kill Switch，
原因填'行为异常 — 调查中'。"

配置回滚

审查并回滚一个错误的配置变更。

"列出 agent coordinator 最近 5 个配置快照。
对比版本 3 和 4 的 diff，然后预览回滚到版本 3。"

审计追查

搜索审计事件，追踪谁在什么时候做了什么变更。

"搜索最近 3 天 risk_level=high 的审计事件。
显示最新一条的完整详情。"

连接器诊断

诊断网关连接问题。

"列出我的连接器。OpenClaw 网关似乎变慢了 —
对它运行一次诊断，告诉我什么问题。"

Runtime Host 发现与托管检查

在已配对机器上发现 Hermes / Claude Code / Codex / OpenClaw 实例，只接入需要治理的实例，把 attach-mode 会话投影到 ClawButler，并继续查看托管会话摘要与待审批请求。

"列出我的 Runtime Hosts。对已配对的 MacBook 执行发现，
把 Codex 和 Claude Code 实例添加成 connectors，
然后同步最近的 attach-mode 会话供调查使用，
再显示 Codex 实例的托管会话，
并列出待处理的托管审批请求。"

「Tool not found」或 IDE 中不显示工具

确认 clawbutler-mcp 已安装且命令路径正确。运行 `uvx clawbutler-mcp --help` 验证。检查 IDE 的 MCP 日志是否有连接错误。

401 Unauthorized / 认证错误

确认 CLAWBUTLER_TOKEN 设置正确。长期自动化建议通过 API 或 `ap service-token create` 创建组织级 service token；短期交互式场景仍可继续使用普通用户 access token。

连接被拒绝 / 超时

检查 CLAWBUTLER_API_URL 指向正在运行的 ClawButler 实例。自部署环境需确保 MCP Server 运行的机器可以访问到 API。

工具可以调用但返回空数据

通常是因为 API 返回了空数组 — 你的实例可能还没有配置 Agent/成本/连接器。先试 get_dashboard 验证连通性。

如何在 Docker / 远程服务器中使用？

使用 HTTP 传输：`clawbutler-mcp --transport http --port 8080`。这会启动一个 Streamable HTTP 服务，任何 MCP 客户端都可以通过网络连接。