mcp-debezium

mcp-debezium

一个用于 Debezium（通过 Kafka Connect REST API）的 Model Context Protocol 服务。它让支持 MCP 的客户端（Claude Desktop、Claude Code 等）能够监控和管理变更数据捕获连接器，包括状态、配置、重启和生命周期；行为完全由标志控制。

默认安全：启动时为只读模式，可将作用范围限制为允许列表中的连接器，保护关键连接器不受更改，隐藏连接器配置中的凭据，并通过显式选择启用删除。

功能

• 监控 — 工作节点／集群信息、连接器列表、插件、每个连接器的配置、状态（含失败任务的跟踪信息）和主题。
• 管理 — 创建／更新、暂停／恢复、重启连接器或单个任务。
• 生命周期 — 删除连接器（管理员）。
• 访问模式 — read-only → read-write → admin，按层级开放，模式不会暴露高于自身级别的工具。
• 凭据隐藏 — 在返回结果前，将 database.password 和其他类似机密的配置值替换为 ***REDACTED***。
• 安全标志 — 连接器允许列表、受保护的连接器、删除门控、试运行和 JSON 审计日志（见下文）。

安全模型

关注事项	标志	默认值	效果
服务可以执行哪些操作？	DEBEZIUM_MODE	read-only	read-only 仅开放监控；read-write 增加生命周期管理；admin 增加删除功能。高于当前模式的工具永远不会注册。
哪些连接器在作用范围内？	DEBEZIUM_CONNECTOR_ALLOWLIST	（全部）	设置后，将拒绝对其他连接器执行操作。
哪些连接器始终为只读？	DEBEZIUM_PROTECTED_CONNECTORS	（无）	可以检查，但永远不会暂停／重新配置／删除。
是否可以删除？	DEBEZIUM_ALLOW_DELETE	false	delete_connector 需要启用此项且使用管理员模式。
预览操作而不触碰 Connect	DEBEZIUM_DRY_RUN	false	写入／管理员工具会进行验证并记录操作意图，然后返回。
审计跟踪	DEBEZIUM_AUDIT_LOG	true	每次受保护的操作都会向 stderr 输出一行 JSON。
交互式确认	（自动）	—	执行破坏性和高影响操作前，会通过 MCP elicitation 提示用户批准；不支持 elicitation 的客户端则回退到 *_ALLOW_* 门控。
凭据隐藏	（始终启用）	—	返回前会隐藏类似机密的配置值。

工具

读取（read-only+）：cluster_info、list_connectors、list_connector_plugins、get_connector、get_connector_config、get_connector_status、get_connector_topics

写入（read-write+）：create_connector、update_connector_config、pause_connector、resume_connector、restart_connector、restart_task

管理员（admin）：delete_connector（需要 DEBEZIUM_ALLOW_DELETE）

快速开始 — 添加到你的 Agent

已发布到 npm，包名为 @dockndevai/mcp-debezium。无需克隆或构建，MCP 客户端会按需通过 npx 运行它。请从 read-only 模式开始；所有变量请参阅 .env.example，各客户端的完整指南请参阅 docs/CLIENTS.md。

Claude Code（命令行）

claude mcp add debezium -e CONNECT_URL="http://localhost:8083" -e DEBEZIUM_MODE="read-only" -- npx -y @dockndevai/mcp-debezium

Claude Desktop · Cursor · Windsurf — 在 claude_desktop_config.json、.cursor/mcp.json 或 ~/.codeium/windsurf/mcp_config.json 中使用相同的配置块：

{
  "mcpServers": {
    "debezium": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-debezium"
      ],
      "env": {
        "CONNECT_URL": "http://localhost:8083",
        "DEBEZIUM_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — 在 ~/.codex/config.toml 中：

[mcp_servers.debezium]
command = "npx"
args = ["-y", "@dockndevai/mcp-debezium"]
env = { CONNECT_URL = "http://localhost:8083", DEBEZIUM_MODE = "read-only" }

VS Code（GitHub Copilot，Agent 模式） — 在 .vscode/mcp.json 中：

{
  "servers": {
    "debezium": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-debezium"
      ],
      "env": {
        "CONNECT_URL": "http://localhost:8083",
        "DEBEZIUM_MODE": "read-only"
      }
    }
  }
}

示例提示词

• “哪些连接器处于 FAILED 状态，原因是什么？”
• “重启 pg-orders 上失败的任务。”（需要 read-write）
• “显示 mysql-inventory 的配置。”（凭据会以脱敏形式返回）

从源代码运行（开发）

建议使用上文发布的包。要从克隆的仓库运行：

npm install
npm run build
node dist/index.js   # with the environment variables set

开发

npm run dev
npm test          # security policy + config redaction
npm run typecheck

发布

此服务提供用于官方 MCP 注册表的 server.json，以及用于 npm 所有权验证的 mcpName。有关发布到 npm，以及在 MCP 注册表、Smithery、Glama、Cursor 和 PulseMCP 上列出的说明，请参阅 PUBLISHING.md。

许可证

MIT