Confluent MCP Server

Yapay zeka asistanlarının Confluent Cloud, Confluent Platform ve bağımsız Apache Kafka dağıtımlarıyla doğal dil aracılığıyla etkileşime girmesini sağlayan açık kaynaklı bir MCP sunucusu. Kafka, Flink SQL, Schema Registry, Connectors, Tableflow ve daha fazlası arasında 50+ araç sağlar -- Claude Desktop, Claude Code, Cursor, VS Code, Goose ve Gemini CLI dahil olmak üzere herhangi bir MCP uyumlu istemcisinden kullanılabilir.

Hızlı Başlangıç

Ön Koşullar: Node.js 22+. Confluent Cloud ile etkileşim kurmak istiyorsanız, önce bir hesap oluşturmanız gerekir.

1. Proje kökünüzde hızlı bir config.yaml dosyası oluşturun:

npx @confluentinc/mcp-confluent --init-config

2. config.yaml dosyasını bağlantı detaylarınızla düzenleyin, ardından:

npx @confluentinc/mcp-confluent --config ./config.yaml

Tam kurulum talimatları için Getting Started bölümüne ve tercih ettiğiniz AI aracıyla entegrasyon için Configuring MCP Clients bölümüne bakın.

İçindekiler

• Hızlı Başlangıç
• Mevcut Araçlar
  • Her Zaman Mevcut
  • Confluent Cloud
  • Yerel dağıtımlar
• Getting Started
• Konfigürasyon
• Confluent Cloud için OAuth Kimlik Doğrulaması
• CLI Kullanımı
• MCP İstemcilerini Yapılandırma
• Telemetri
• Sorun Giderme
• Katkıda Bulunma

Mevcut Araçlar

Araçlar, çözümlenen konfigürasyonunuzda hangi hizmet bloklarının mevcut olduğuna göre otomatik olarak etkinleştirilir; tam blok-araç eşlemesi için CONFIGURATION.md bölümüne bakın.

Tüm mevcut araçları CLI aracılığıyla listeleyebilirsiniz:

npx -y @confluentinc/mcp-confluent --list-tools

Her Zaman Mevcut Araçlar

Bu araçlar hizmet bloklarına veya kimlik doğrulamaya ihtiyaç yoktur -- yapılandırmanızın geri kalanı hangi dağıtımı hedefse hedeflesin, boş bir konfigürasyon üzerinde bile etkinleştirilirler.

Confluent Cloud için Mevcut Araçlar

Bu araçlar, belirli Confluent Cloud bileşenlerine karşı endpoint ve kimlik doğrulamayı gerektirir. Tam konfigürasyon değişkenleri seti için config.example.yaml dosyasına bakın. ¹ ile işaretlenen kategoriler ayrıca OAuth kimlik doğrulaması ile de çalışır -- API anahtarlarını sağlamak yerine tarayıcınız aracılığıyla oturum açın.

¹ OAuth altında da mevcuttur -- kurulum ve uyarılar için Confluent Cloud için OAuth Kimlik Doğrulaması bölümüne bakın. İşaretlenmemiş kategoriler şu anda statik API anahtarları ile direct bağlantı gerektirir; OAuth geçişi devam etmektedir.

Yerel Dağıtımlar için Mevcut Araçlar

Bu araçlar yalnızca Kafka veya Schema Registry endpoint'lerine ihtiyaç duyar - Confluent Cloud API anahtarı/gizli anahtarı gerekli değildir. Confluent Platform dahil olmak üzere kendi kendini yöneten kümeler ile yerel geliştirme için idealdir.

# yerel geliştirme için minimal config.yaml
connections:
  local:
    type: direct
    kafka:
      bootstrap_servers: "localhost:9092"
    schema_registry:
      endpoint: "http://localhost:8081"

Kullanıma hazır varyantlar sample_configs/ dizininde bulunur.

Getting Started

Ön Koşullar

• Node.js 22 veya üzeri -- sürümleri yönetmek için NVM kullanmanızı öneririz:

  nvm install 22
  nvm use 22
  

• Kafka veya Schema Registry çalışan bir yerel ortam veya OAuth kullanarak kimlik doğrulaması yaparken uygun API anahtarları veya giriş kimlik bilgileri ile bir Confluent Cloud hesabı.

Genel Kurulum Adımları

Bu MCP sunucusu, Claude Desktop, Copilot veya Goose CLI/Desktop gibi çeşitli MCP istemcileri ile kullanılmak üzere tasarlanmıştır. Belirli konfigürasyon ve etkileşim, kullandığınız istemciye bağlıdır.

MCP sunucusu, yapılandırma dosyasında tanımlanan statik API anahtarlarına ek olarak OAuth (PKCE) aracılığıyla Confluent Cloud'a kimlik doğrulaması yapabilir. Daha fazla bilgi için Confluent Cloud için OAuth Kimlik Doğrulaması bölümüne bakın.

Genel kurulum adımları (OAuth kullanmıyorsanız) ve bu MCP'yi çalıştırma:

1. Konfigürasyon dosyası oluşturun: Sağlanan config.yaml örneğini projenizin köküne kopyalayın. CLI'yı kullanarak geçerli dizininizde bir tane oluşturabilirsiniz -- git checkout gerekli değildir:

npx @confluentinc/mcp-confluent --init-config

2. Dosyayı doldurun: Confluent Cloud ortamınız için gerekli değerleri girin. Tam referans için CONFIGURATION.md bölümüne bakın; yalnızca ihtiyaç duyduğunuz hizmet bloklarını doldurun (her biri araç grubu etkinleştirir).

3. Sunucuyu Başlatın: MCP sunucusunu iki şekilde çalıştırabilirsiniz:

   • Kaynaktan: Sunucuyu kaynaktan oluşturmak ve çalıştırmak için Katkıda Bulunma Rehberi talimatlarını izleyin. Bu genellikle şunları içerir:

     • Bağımlılıkları yükleme (npm install)
     • Projeyi oluşturma (npm run build veya npm run dev)

   • npx ile: npx kullanarak sunucuyu doğrudan başlatabilirsiniz, derleme gerekli değildir:

     npx @confluentinc/mcp-confluent --config /path/to/myconfig.yaml
     

4. MCP İstemcinizi Yapılandırın: Her istemcinin (örneğin Claude, Goose) MCP sunucusunun adresini ve gerekli kimlik bilgilerini belirtmenin kendi yöntemi olacaktır. İstemcinizi, bu sunucunun çalıştığı adrese bağlanacak şekilde yapılandırmanız gerekecektir (muhtemelen belirli bir port ile localhost). Sunucunun çalıştığı port config.yaml dosyasında server.http.port aracılığıyla ayarlanır.

5. MCP İstemcinizi Başlatın: İstemciniz MCP sunucusuna bağlanacak şekilde yapılandırıldıktan sonra, MCP istemcinizi başlatabilir ve başlangıçta bu MCP sunucusunun yerel bir örneğini kurabilir. Bu örnek, veri şemalarını yönetmek ve kaynaklar ile etkileşime girmek için sorumlu olacaktır.

6. Kaynakları İstemci Aracılığıyla Yönetin: İstemci bağlandıktan ve yapılandırıldıktan sonra, Confluent Cloud veya yerel kaynakları yönetmek için istemcinin arayüzünü kullanabilirsiniz. İstemci bu MCP sunucusuna istek gönderecek, sunucu da sizin adınıza mevcut bağlantılar ile etkileşime girecektir.

Konfigürasyon

Tam konfigürasyon referansı -- YAML şeması, her hizmet bloğu, env-var interpolasyonu, OAuth ve HTTP/SSE auth kurulumu, (kullanımdan kaldırılan) eski env-var tablosu ve araç-blok eşlemesi -- CONFIGURATION.md dosyasında bulunur.

Uyumluluk notu. Bu sürüm, tek bir bağlantı için YAML (-c config.yaml) ve eski env-var yolu (-e config.env) arasında tam pariteyi içerir. Env-var yolu, yakın gelecekte bir sürümde başlangıç uyarısı yayınlayacak ve bir-iki sürüm sonra kaldırılacaktır. Multi-bağlantı desteği (sonraki sürüm) yalnızca YAML olacaktır. CONFIGURATION.md → Two paths, one configuration bölümüne bakın.

Tableflow Komutları için Ön Koşullar ve Kurulum

Tableflow araçları, Confluent Cloud'daki Flink runtime aracılığıyla sizin adınıza bulut depolama (ör. AWS S3) ve metadata catalog (ör. AWS Glue) ile etkileşime girer. Flink runtime'ı bulut hesabınızda IAM izinlerine ihtiyaç duyar ve bu izinler, herhangi bir Tableflow aracının başarılı olmasından önce Confluent Cloud'a verilmeli ve bağlanmalıdır.

Rolleri, politikaları ve sağlayıcı entegrasyonlarını kurmak için Tableflow quick start with custom storage & Glue bölümünü izleyin. Bu adımı atlamak, mcp-confluent Tableflow özellikli tabloları sağlamaya veya yönetmeye çalıştığında yetki hatalarına neden olur.

Confluent Cloud için OAuth Kimlik Doğrulaması

MCP sunucusu, statik API anahtarları yerine OAuth (PKCE) aracılığıyla Confluent Cloud'a kimlik doğrulaması yapabilir. Confluent Cloud erişimi gerektiren ilk araç çağrısında, sunucu tarayıcınızı Confluent Cloud oturum açma sayfasına açar; sonraki araç çağrıları ortaya çıkan oturumu yeniden kullanır. Sağlanması gereken API anahtarları yok.

Kurulum

npx @confluentinc/mcp-confluent --init-oauth-config
# gerekirse ./config.yaml dosyasını düzenleyin, ardından:
npx @confluentinc/mcp-confluent --config ./config.yaml

--init-oauth-config, başlangıç config.oauth.example.yaml dosyasını ./config.yaml dosyasına düşürür. Dosyanın tamamı temelde şundan oluşur:

connections:
  ccloud-oauth:
    type: oauth

Tam şema ve ergonomik özellikler için CONFIGURATION.md → Authentication modes bölümüne bakın.

Confluent Cloud için Mevcut Araçlar bölümünde ¹ ile işaretlenen kategoriler bugün OAuth altında çalışır; diğer her şey hala statik API anahtarları ile direct bağlantı gerektirir.

CLI Kullanımı

MCP sunucusu, gelişmiş kontrol için esnek bir komut satırı arayüzü (CLI) sağlar. CLI, konfigürasyon dosyasını, aktarımları seçmenize ve hangi araçların etkinleştirildiğini veya engelleneceğini ince ayarlamanızı sağlar.

Temel Kullanım

Tüm CLI seçeneklerini ve yardımı şu şekilde görüntüleyebilirsiniz:

npx @confluentinc/mcp-confluent --help

Usage: mcp-confluent [options]

Confluent MCP Server - Model Context Protocol implementation for Confluent Cloud

Options:
  -V, --version                    output the version number
  -e, --env-file <path>            Load environment variables from file
  -k, --kafka-config-file <file>   Path to a properties file for configuring kafka clients
  -t, --transport <types>          Transport types (comma-separated list) (choices: "http", "sse", "stdio", default: "stdio")
  --allow-tools <tools>            Comma-separated list of tool names to allow. If provided, takes precedence over --allow-tools-file. Allow-list is applied before block-list.
  --block-tools <tools>            Comma-separated list of tool names to block. If provided, takes precedence over --block-tools-file. Block-list is applied after allow-list.
  --allow-tools-file <file>        File with tool names to allow (one per line). Used only if --allow-tools is not provided. Allow-list is applied before block-list.
  --block-tools-file <file>        File with tool names to block (one per line). Used only if --block-tools is not provided. Block-list is applied after allow-list.
  --list-tools                     Print the final set of enabled tool names (with descriptions) after allow/block filtering and exit. Does not start the server.
  --disable-auth                   Disable authentication for HTTP/SSE transports. WARNING: Only use in development environments.
  --allowed-hosts <hosts>          Comma-separated list of allowed Host header values for DNS rebinding protection.
  --generate-key                   Generate a secure API key for MCP_API_KEY and print it to stdout, then exit.
  -h, --help                       display help for command

Örnek: Tüm Aktarımları Kullanarak Dağıtma

npx @confluentinc/mcp-confluent -c config.yaml --transport http,sse,stdio

...
{"level":"info","time":"2025-05-14T17:03:02.883Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"Starting transports: http, sse, stdio"}
{"level":"info","time":"2025-05-14T17:03:02.971Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"HTTP transport routes registered"}
{"level":"info","time":"2025-05-14T17:03:02.972Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"SSE transport routes registered"}
{"level":"info","time":"2025-05-14T17:03:02.972Z","pid":47959,"hostname":"G9PW1FJH64","name":"mcp-confluent","msg":"STDIO transport connected"}
{"level":"info","time":"2025-05-14T17:03:03.012Z","pid":47959,"hostname":"G9PW1FJH64","msg":"Server listening at http://[::1]:3000"}
{"level":"info","time":"2025-05-14T17:03:03.013Z","pid":47959,"hostname":"G9PW1FJH64","msg":"Server listening at http://127.0.0.1:3000"}
{"level":"info","time":"2025-05-14T17:03:03.013Z","pid":47959,"hostname":"G9PW1FJH64","msg":"All transports started successfully"}

Örnek: Yalnızca Belirli Araçlara İzin Ver

npx @confluentinc/mcp-confluent -c config.yaml --allow-tools produce-message,consume-messages

Yalnızca belirtilen araçlar etkinleştirilecek; diğer tümü devre dışı bırakılacaktır.

Örnek: Belirli Araçları Engelle

npx @confluentinc/mcp-confluent -c config.yaml --block-tools produce-message,consume-messages

Belirtilen araçlar hariç tüm araçlar etkinleştirilecektir.

Örnek: Dosyalardan Araç Listelerini Kullan

Ayrıca izin verir/engeller listeleri dosyalarda saklayabilirsiniz (her satırda bir araç adı):

npx -y @confluentinc/mcp-confluent -c config.yaml --allow-tools-file allow.txt --block-tools-file block.txt

Örnek: Tüm Mevcut Araçları Listele

npx -y @confluentinc/mcp-confluent --list-tools

add-tags-to-topic: Assign existing tags to Kafka topics in Confluent Cloud.
alter-topic-config: Alter topic configuration in Confluent Cloud.
consume-messages: Consumes messages from one or more Kafka topics. Supports automatic deserialization of Schema Registry encoded messag...
create-connector: Create a new connector. Returns the new connector information if successful.
create-flink-statement: Make a request to create a statement.
create-topic-tags: Create new tag definitions in Confluent Cloud.
create-topics: Create one or more Kafka topics.
delete-connector: Delete an existing connector. Returns success message if deletion was successful.
delete-flink-statements: Make a request to delete a statement.
delete-tag: Delete a tag definition from Confluent Cloud.
delete-topics: Delete the topic with the given names.
check-flink-statement-health: Perform an aggregate health check for a Flink SQL statement.
describe-consumer-group: Describe a single consumer group on a Kafka cluster — wraps the broker's describeGroups admin call for one group ID. Returns state, type, protocol, coordinator, and per-member assignment.
get-consumer-group-lag: Compute live offset lag for a single Kafka consumer group. Returns per-(topic, partition) {committedOffset, highWatermark, lag} rows and a total lag count across the group.
describe-flink-table: Get full schema details for a Flink table via INFORMATION_SCHEMA.COLUMNS.
detect-flink-statement-issues: Detect issues for a Flink SQL statement by analyzing status, exceptions, and metrics.
get-flink-statement-profile: Get Query Profiler data with task graph, metrics, and automated issue detection.
get-flink-table-info: Get table metadata via INFORMATION_SCHEMA.TABLES.
list-flink-catalogs: List all catalogs in the Flink environment.
list-flink-databases: List all databases (schemas) in a Flink catalog via INFORMATION_SCHEMA.SCHEMATA.
list-flink-tables: List all tables in a Flink database.
get-flink-statement-exceptions: Retrieve the 10 most recent exceptions for a Flink SQL statement.
get-topic-config: Retrieve configuration details for a specific Kafka topic.
list-clusters: Get all clusters in the Confluent Cloud environment
list-connectors: Retrieve a list of "names" of the active connectors. You can then make a read request for a specific connector by name.
list-consumer-groups: List consumer groups on a Kafka cluster — wraps the broker's listGroups admin call. Optional filters narrow the resul...
list-environments: Get all environments in Confluent Cloud with pagination support
list-flink-statements: Retrieve a sorted, filtered, paginated list of all statements.
list-schemas: List all schemas in the Schema Registry.
list-tags: Retrieve all tags with definitions from Confluent Cloud Schema Registry.
list-topics: List all topics in the Kafka cluster.
produce-message: Produce records to a Kafka topic. Supports Confluent Schema Registry serialization (AVRO, JSON, PROTOBUF) for both ke...
read-connector: Get information about the connector.
read-environment: Get details of a specific environment by ID
read-flink-statement: Make a request to read a statement and its results
remove-tag-from-entity: Remove tag from an entity in Confluent Cloud.
search-topics-by-name: List all topics in the Kafka cluster matching the specified name.
search-topics-by-tag: List all topics in the Kafka cluster with the specified tag.
create-tableflow-topic: Make a request to create a tableflow topic.
list-tableflow-regions: Retrieve a sorted, filtered, paginated list of all tableflow regions.
list-tableflow-topics: Retrieve a sorted, filtered, paginated list of all tableflow topics.
read-tableflow-topic: Make a request to read a tableflow topic.
update-tableflow-topic: Make a request to update a tableflow topic.
delete-tableflow-topic: Make a request to delete a tableflow topic.
create-tableflow-catalog-integration: Make a request to create a catalog integration.
list-tableflow-catalog-integrations: Retrieve a sorted, filtered, paginated list of all catalog integrations.
read-tableflow-catalog-integration: Make a request to read a catalog integration.
update-tableflow-catalog-integration: Make a request to update a catalog integration.
delete-tableflow-catalog-integration: Make a request to delete a tableflow catalog integration.
list-organizations: List Confluent Cloud organizations the current credentials can see. Paginated; if the response includes a nextPageToken, pass it back as pageToken to fetch additional pages.
explain-disabled-tools: Call when the user asks why a tool is missing or unavailable (e.g., "why can't I list Kafka topics?", "where are the Flink tools?"). Returns disabled tools grouped by the config gap each one is waiting on, so you can tell the user the exact YAML block or field to add. Prefer this over guessing about credentials, network, or auth.

İpucu: İzin listesi, engel listesinden önce uygulanır. İkisi de sağlanmazsa, tüm araçlar varsayılan olarak etkinleştirilir.

MCP İstemcilerini Yapılandırma

Tercih ettiğiniz istemci ile bu MCP sunucusunu ayarlamak ve kullanmak için adım adım talimatlar için lütfen aşağıdaki rehberlere başvurun:

• [Claude Code](docs/config