mcp-confluent

An MCP server implementation that enables AI assistants to interact with Confluent Cloud REST APIs. This server allows AI tools like Claude Desktop and Goose CLI to manage Kafka topics, connectors, and Flink SQL statements through natural language interactions.

Demo

Goose CLI

Claude Desktop

Related MCP server: MCP Server

Table of Contents

• mcp-confluent

  • Demo

    • Goose CLI

    • Claude Desktop

  • Table of Contents

  • User Guide

    • Getting Started

    • Configuration

      • Prerequisites & Setup for Tableflow Commands

    • Environment Variables Reference

    • Usage

    • Configuring Claude Desktop

    • Configuring Goose CLI

    • Configuring Gemini CLI

    • mcp-confluent CLI Usage

      • Basic Usage

      • Example: Deploy using all transports

      • Example: Allow Only Specific Tools

      • Example: Block Certain Tools

      • Example: Use Tool Lists from Files

      • Example: List All Available Tools

  • Developer Guide

    • Project Structure

    • Building and Running

    • Docker

      • Prerequisites

        • Environment Variables

      • Building and Running with Docker

      • Building and Running with Docker Compose

    • Testing

      • MCP Inspector

    • Adding a New Tool

    • Generating Types

    • Contributing

User Guide

Getting Started

1. Create a Copy the example .env file structure (shown below) into a new file named .env in the root of your project.

2. Populate the Fill in the necessary values for your Confluent Cloud environment. See the Configuration section for details on each variable.

3. Install Node.js (if not already installed)

   • We recommend using NVM (Node Version Manager) to manage Node.js versions

   • Install and use Node.js:

   nvm install 22 nvm use 22

Configuration

Create a .env file in the root directory of your project with the following configuration:

Prerequisites & Setup for Tableflow Commands

In order to leverage Tableflow commands to interact with your data ecosystem and successfully execute these Tableflow commands and manage resources (e.g., interacting with data storage like AWS S3 and metadata catalogs like AWS Glue), certain IAM (Identity and Access Management) permissions and configurations are essential.

It is crucial to set up the necessary roles and policies in your cloud environment (e.g., AWS) and link them correctly within Confluent Cloud. This ensures your Flink SQL cluster, which powers Tableflow, has the required authorization to perform operations on your behalf.

Please refer to the following Confluent Cloud documentation for detailed instructions on setting up these permissions and integrating with custom storage and Glue:

• Confluent Cloud Tableflow Quick Start with Custom Storage & Glue: https://docs.confluent.io/cloud/current/topics/tableflow/get-started/quick-start-custom-storage-glue.html

Ensuring these prerequisites are met will prevent authorization errors when the mcp-server attempts to provision or manage Tableflow-enabled tables.

Environment Variables Reference

Usage

This MCP server is designed to be used with various MCP clients, such as Claude Desktop or Goose CLI/Desktop. The specific configuration and interaction will depend on the client you are using. However, the general steps are:

1. Start the Server: You can run the MCP server in one of two ways:

   • From source: Follow the instructions in the Developer Guide to build and run the server from source. This typically involves:

     • Installing dependencies (npm install)

     • Building the project (npm run build or npm run dev)

   • With npx: You can start the server directly using npx (no build required):

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

2. Configure your MCP Client: Each client will have its own way of specifying the MCP server's address and any required credentials. You'll need to configure your client (e.g., Claude, Goose) to connect to the address where this server is running (likely localhost with a specific port). The port the server runs on may be configured by an environment variable.

3. Start the MCP Client: Once your client is configured to connect to the MCP server, you can start your mcp client and on startup - it will stand up an instance of this MCP server locally. This instance will be responsible for managing data schemas and interacting with Confluent Cloud on your behalf.

4. Interact with Confluent through the Client: Once the client is connected, you can use the client's interface to interact with Confluent Cloud resources. The client will send requests to this MCP server, which will then interact with Confluent Cloud on your behalf.

Configuring Claude Desktop

See here for more details about installing Claude Desktop and MCP servers.

To configure Claude Desktop to use this MCP server:

1. Open Claude Desktop Configuration

   • On Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

   • On Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Edit Configuration File

   • Open the config file in your preferred text editor

   • Add or modify the configuration using one of the following methods:

   { "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" ] } } }

   Replace /path/to/confluent-mcp-server/ with the actual path where you've installed this MCP server.

3. Restart Claude Desktop

   • Close and reopen Claude Desktop for the changes to take effect

   • The MCP server will automatically start when Claude Desktop launches

Now Claude Desktop will be configured to use your local MCP server for Confluent interactions.

Configuring Goose CLI

See here for detailed instructions on how to install the Goose CLI.

Once installed, follow these steps:

1. Run the Configuration Command:

   goose configure

2. Follow the Interactive Prompts:

   • Select Add extension

   • Choose Command-line Extension

   • Enter mcp-confluent as the extension name

   • Choose one of the following configuration methods:

   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

Replace /path/to/confluent-mcp-server/ with the actual path where you've installed this MCP server.

Configuring Gemini CLI

For detailed information about Gemini CLI extensions and MCP servers, please refer to the official documentation:

• Gemini CLI Extensions

• Gemini CLI MCP Server Tools

Here's how to get mcp-confluent running with Gemini CLI:

1. Install Gemini CLI: If you haven't already, install the Gemini CLI. You can find installation instructions on the official GitHub repository.

2. Install the

   gemini extensions install https://github.com/confluentinc/mcp-confluent # Navigate to the root directory of this project (where `gemini-extension.json` is located) and run: # gemini extensions install .

   This command registers the mcp-confluent server with Gemini CLI and creates a dedicated directory for it under ~/.gemini/extensions/mcp-confluent.

3. Provide Environment Variables: The extension requires your Confluent Cloud credentials and configuration to be available in a .env file.

   • First, ensure you have a correctly populated .env file in the root of this project. For instructions, see the Configuration section.

   • Next, copy your .env file into the extension's directory so Gemini CLI can access it (the Gemini extension expects the .env file at ${extensionPath}${pathSeparator}.env; see the variables documentation for details):

   cp .env ~/.gemini/extensions/mcp-confluent/.env

4. Verify and Use: You can now start using the Confluent tools via Gemini CLI. To verify that the tools are available, you can list them:

   gemini -l # or `gemini extensions list`

   And here's an example of invoking a tool:

   gemini .... 🟢 mcp-confluent (from mcp-confluent) - Ready (24 tools) .... Using: 1 MCP server (ctrl+t to toggle) ╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ > list topics │ ╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ✓ list-topics (mcp-confluent MCP Server) {} │ │ │ │ Kafka topics: │ │ products_summarized,products,topic_8,products_summarized_with_embeddings,elastic_minimized,user_message_related_products,user_message_embeddin │ │ gs,dlq-lcc-d3738o,user_message,elastic │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ✦ Okay, I see the following topics: products_summarized, products, topic_8, products_summarized_with_embeddings, elastic_minimized, user_message_related_products, user_message_embeddings, dlq-lcc-d3738o, user_message, and elastic.

mcp-confluent CLI Usage

The MCP server provides a flexible command line interface (CLI) for advanced configuration and control. The CLI allows you to specify environment files, transports, and fine-tune which tools are enabled or blocked.

Basic Usage

You can view all CLI options and help with:

Example: Deploy using all transports

Example: Allow Only Specific Tools

Example: Block Certain Tools

Example: Use Tool Lists from Files

Example: List All Available Tools

Tip: The allow-list is applied before the block-list. If neither is provided, all tools are enabled by default.

Developer Guide

Project Structure

Building and Running

1. Install Dependencies:

   npm install

2. Development Mode (watch for changes):

   npm run dev

   This command compiles the TypeScript code to JavaScript and automatically rebuilds when changes are detected in the src/ directory.

3. Production Build (one-time compilation):

   npm run build

4. Start the Server:

   npm run start

Docker

Prerequisites

Before you begin, ensure you have the following installed on your system:

Docker Desktop (or Docker Engine and Docker Compose): https://www.docker.com/products/docker-desktop

Environment Variables

The MCP server requires several environment variables to connect to Confluent Cloud and other relevant services. These should be provided in the .env file in the root directory of this project. Or you can add them directly in the docker-compose.yml

Building and Running with Docker

Here's how to build your Docker image and run it in different modes.

1. Navigate to your project directory. Open your terminal or command prompt and change to the directory containing the Dockerfile.

   cd /path/to/repo/mcp-confluent

2. Build the Docker image.

   This command creates the mcp-server image based on the Dockerfile in the current directory.

   docker build -t mcp-server .

3. Run the container

   • --rm: Automatically removes the container when it exits. This helps keep your system clean.

   • -i: Keeps STDIN open (runs the server using stdio transport by default).

   • -d: Runs the container in detached mode (in the background).

   • -p 3000:3000: Maps port 3000 on your host machine to port 3000 inside the container. Adjust this if your app listens on a different port.

   docker run --rm -i -d -p 3000:3000 mcp-server

   (Optional)

   • -t Transport Mode to enable http transport

   docker run --rm -d -p 3000:3000 mcp-server -t http

Building and Running with Docker Compose

1. Navigate to the project root: Open your terminal or command prompt and change to the directory containing Dockerfile and docker-compose.yml.

   cd /path/to/repo/mcp-confluent

2. Build and run the service: Docker Compose will build the Docker image (if not already built) and start the mcp-server service.

   docker compose up --build

   The --build flag ensures that Docker Compose rebuilds the image before starting the container. You can omit this flag on subsequent runs if you haven't changed the Dockerfile or source code.

   The server will be accessible on http://localhost:3000 (or the port specified in HTTP_PORT in your .env file).

3. Stopping the Server To stop the running MCP server and remove the containers, press Ctrl+C in the terminal where docker compose up is running.

   Alternatively, in a new terminal from the project root, you can run:

   docker compose down

   This command stops and removes the containers, networks, and volumes created by docker compose up.

Testing

MCP Inspector

For testing MCP servers, you can use MCP Inspector which is an interactive developer tool for testing and debugging MCP servers.

Adding a New Tool

1. Add a new enum to the enum class ToolName.

2. Add your new tool to the handlers map in the ToolFactory class.

3. Create a new file, exporting the class that extends BaseToolHandler.

   1. Implement the handle method of the base class.

   2. Implement the getToolConfig method of the base class.

4. Once satisfied, add it to the set of enabledTools in index.ts.

Generating Types

Contributing

Bug reports and feedback is appreciated in the form of Github Issues. For guidelines on contributing please see CONTRIBUTING.md