mcp-confluent

一个MCP服务器实现，使AI助手能够与Confluent Kafka和Confluent Cloud REST APIs交互。该服务器允许像Claude Desktop和Goose CLI这样的AI工具通过自然语言交互来管理Kafka主题、连接器和Flink SQL语句。

演示

Goose CLI

Claude Desktop

目录

• mcp-confluent
  • 演示
    • Goose CLI
    • Claude Desktop
  • 目录
  • 用户指南
    • 开始使用
    • 配置
    • 环境变量参考
    • 用法
    • 配置Claude Desktop
    • 配置Goose CLI
  • 开发者指南
    • 项目结构
    • 构建与运行
    • 测试
      • MCP Inspector
    • 添加新工具
    • 生成类型
    • 贡献

用户指南

开始使用

1. 创建一个.env文件： 将示例的.env文件结构（如下所示）复制到你的项目根目录下的一个名为.env的新文件中。

2. 填充.env文件： 根据您的Confluent Cloud环境填写必要的值。有关每个变量的详细信息，请参见配置部分。

3. 安装Node.js（如果尚未安装）

   • 我们建议使用NVM（Node版本管理器）来管理Node.js版本
   • 安装并使用Node.js：

   nvm install 22
   nvm use 22
   

配置

在项目的根目录下创建一个包含以下配置的.env文件：

# .env file
BOOTSTRAP_SERVERS="pkc-v12gj.us-east4.gcp.confluent.cloud:9092"
KAFKA_API_KEY="..."
KAFKA_API_SECRET="..."
KAFKA_REST_ENDPOINT="https://pkc-v12gj.us-east4.gcp.confluent.cloud:443"
KAFKA_CLUSTER_ID=""
KAFKA_ENV_ID="env-..."
FLINK_ENV_ID="env-..."
FLINK_ORG_ID=""
FLINK_REST_ENDPOINT="https://flink.us-east4.gcp.confluent.cloud"
FLINK_ENV_NAME=""
FLINK_DATABASE_NAME=""
FLINK_API_KEY=""
FLINK_API_SECRET=""
FLINK_COMPUTE_POOL_ID="lfcp-..."
CONFLUENT_CLOUD_API_KEY=""
CONFLUENT_CLOUD_API_SECRET=""
CONFLUENT_CLOUD_REST_ENDPOINT="https://api.confluent.cloud"
SCHEMA_REGISTRY_API_KEY="..."
SCHEMA_REGISTRY_API_SECRET="..."
SCHEMA_REGISTRY_ENDPOINT="https://psrc-zv01y.northamerica-northeast2.gcp.confluent.cloud"

环境变量参考

使用说明

此MCP服务器设计用于与各种MCP客户端（如Claude桌面版或Goose CLI/桌面版）配合使用。具体的配置和交互将取决于您使用的客户端。但一般步骤如下：

1. 构建： 按照开发者指南中的说明从源代码构建并运行服务器。这通常包括：

   • 安装依赖项 (npm install)
   • 构建项目 (npm run build 或 npm run dev)

2. 配置您的MCP客户端： 每个客户端都有自己的方式来指定MCP服务器的地址及任何所需的凭证。您需要配置您的客户端（例如，Claude, Goose），使其连接到该服务器正在运行的地址（很可能是带有特定端口的localhost）。服务器运行的端口可能通过环境变量配置。

3. 启动MCP客户端： 一旦您的客户端配置为连接到MCP服务器，您可以启动您的MCP客户端，在启动时它将在本地启动一个此MCP服务器的实例。该实例将负责管理数据模式，并代表您与Confluent Cloud进行交互。

4. 通过客户端与Confluent互动： 一旦客户端连接成功，您可以使用客户端界面与Confluent Cloud资源进行交互。客户端会向此MCP服务器发送请求，然后该服务器将代表您与Confluent Cloud进行通信。

配置Claude桌面版

有关安装Claude桌面版和MCP服务器的更多详细信息，请参阅这里。

要配置Claude桌面版以使用此MCP服务器：

1. 打开Claude桌面版配置

   • 在Mac上: ~/Library/Application Support/Claude/claude_desktop_config.json
   • 在Windows上: %APPDATA%\Claude\claude_desktop_config.json

2. 编辑配置文件

   • 使用您喜欢的文本编辑器打开配置文件
   • 使用以下方法之一添加或修改配置：

   {
     "mcpServers": {
       "confluent": {
         "command": "node",
         "args": [
           "/path/to/confluent-mcp-server/dist/index.js",
            "--env-file",
           "/path/to/confluent-mcp-server/.env",
         ]
       }
     }
   }
   

   {
     "mcpServers": {
       "confluent": {
         "command": "npx",
         "args": [
           "-y"
           "@confluentinc/mcp-confluent",
           "-e",
           "/path/to/confluent-mcp-server/.env"
         ]
       }
     }
   }
   

   将/path/to/confluent-mcp-server/替换为您实际安装此MCP服务器的路径。

3. 重启Claude桌面版

   • 关闭并重新打开Claude桌面版使更改生效
   • MCP服务器将在Claude桌面版启动时自动开始运行

现在将配置 Claude Desktop 以使用您的本地 MCP 服务器进行 Confluent 交互。

配置 Goose CLI

有关如何安装 Goose CLI 的详细说明，请参见这里。

安装完成后，请按照以下步骤操作：

1. 运行配置命令：

   goose configure
   

2. 按照交互提示操作：

   • 选择 Add extension
   • 选择 Command-line Extension
   • 输入 mcp-confluent 作为扩展名
   • 选择以下配置方法之一：

   node /path/to/confluent-mcp-server/dist/index.js --env-file /path/to/confluent-mcp-server/.env
   

   npx -y @confluentinc/mcp-confluent -e /path/to/confluent-mcp-server/.env
   

请将 /path/to/confluent-mcp-server/ 替换为您实际安装此 MCP 服务器的路径。

开发者指南

项目结构

/
├── src/                 # Source code
│   ├── confluent/       # Code related to Confluent integration (API clients, etc.)
│   ├── tools/           # Tool implementations (each tool in a separate file)
│   ├── index.ts         # Main entry point for the server
│   └── ...              # Other server logic, utilities, etc.
├── dist/                # Compiled output (TypeScript -> JavaScript)
├── openapi.json         # OpenAPI specification for Confluent Cloud
├── .env                 # Environment variables (example - should be copied and filled)
├── README.md            # This file
└── package.json         # Node.js project metadata and dependencies

构建和运行

1. 安装依赖项：

   npm install
   

2. 开发模式（监听更改）：

   npm run dev
   

   此命令会将 TypeScript 代码编译为 JavaScript，并在检测到 src/ 目录中的更改时自动重新构建。

3. 生产环境构建（一次性编译）：

   npm run build
   

4. 启动服务器：

   npm run start
   

测试

MCP Inspector

对于测试 MCP 服务器，您可以使用 MCP Inspector，这是一个用于测试和调试 MCP 服务器的交互式开发者工具。

# make sure you've already built the project either in dev mode or by running npm run build
npx @modelcontextprotocol/inspector node  $PATH_TO_PROJECT/dist/index.js --env-file $PATH_TO_PROJECT/.env

添加新工具

1. 在枚举类 ToolName 中添加一个新的枚举。
2. 在 ToolFactory 类的处理程序映射中添加您的新工具。
3. 创建一个新文件，导出继承自 BaseToolHandler 的类。
   1. 实现基类的 handle 方法。
   2. 实现基类的 getToolConfig 方法。
4. 完成后，在 index.ts 中将其添加到 enabledTools 集合中。

生成类型

# as of v7.5.2 there is a bug when using allOf w/ required https://github.com/openapi-ts/openapi-typescript/issues/1474. need --empty-objects-unknown flag to avoid it
npx openapi-typescript ./openapi.json -o ./src/confluent/openapi-schema.d.ts --empty-objects-unknown

贡献

我们非常欢迎以 Github Issues 的形式提交错误报告和反馈。有关贡献指南，请参阅 CONTRIBUTING.md