Kafka Schema Registry MCP Server

What is Kafka Schema Registry MCP Server about?

A Model Context Protocol server that exposes a rich set of tools for managing Kafka Schema Registry instances. It supports read‑only browsing, schema registration/evolution, and full administrative actions such as migration, bulk operations, and disaster‑recovery, all accessible through JSON‑RPC (stdio) and integrated directly with Claude Desktop and other MCP clients.

How to use Kafka Schema Registry MCP Server?

1. Docker (recommended) – pull the stable image and run with the desired edition:

   docker pull aywengo/kafka-schema-reg-mcp:stable
   docker run -e MCP_EDITION=viewer  -e SCHEMA_REGISTRY_URL=http://localhost:8081 aywengo/kafka-schema-reg-mcp:stable
   # editor edition
   docker run -e MCP_EDITION=editor -e SCHEMA_REGISTRY_URL=http://localhost:8081 aywengo/kafka-schema-reg-mcp:stable
   # admin edition
   docker run -e MCP_EDITION=admin -e SCHEMA_REGISTRY_URL=http://localhost:8081 aywengo/kafka-schema-reg-mcp:stable
   

2. Configure Claude Desktop – copy the appropriate JSON config from config-examples/ to the Claude Desktop configuration directory (macOS or Linux paths provided).
3. Local Python execution (optional) – clone the repo, install requirements, and run the main script:

   git clone https://github.com/aywengo/kafka-schema-reg-mcp
   cd kafka-schema-reg-mcp
   pip install -r requirements.txt
   python kafka_schema_registry_unified_mcp.py
   

4. Kubernetes – install via the provided Helm chart: helm install kafka-schema-mcp ./helm/kafka-schema-reg-mcp.

Key Features of Kafka Schema Registry MCP Server

• Three editions – viewer (39 tools), editor (42 tools), admin (66 tools) selectable via MCP_EDITION.
• Multi‑registry support – manage up to 8 registries simultaneously with independent view‑only flags.
• Claude Desktop integration – natural‑language schema generation, evolution, and migration through MCP tools.
• OAuth 2.1 authentication – optional enterprise‑grade security with scope‑based permissions.
• Export capabilities – JSON and Avro IDL formats for backup and documentation.
• Async progress tracking – long‑running operations provide real‑time status and cancellation.
• Docker images – stable, editor, and admin tags; pull‑and‑run ready.
• Comprehensive testing suite – quick and full test scripts, inspector‑driven UI tests.

Use Cases of Kafka Schema Registry MCP Server

• Schema browsing & compliance checks for developers needing a read‑only view of production registries.
• Automated schema creation via Claude Code skills (/schema‑generate, /schema‑evolve).
• Cross‑environment migration – move schemas from staging to production with backup and verification.
• Bulk operations – delete test schemas, export all subjects, count schemas across registries.
• Enterprise security enforcement – require OAuth tokens and enforce read/write scopes per registry.
• CI/CD integration – run the Docker image or Python script in pipelines to validate compatibility before deployment.

FAQ

• What editions are available? viewer (read‑only), editor (adds registration/evolution), admin (full administrative surface). Default is viewer.
• How do I enable write access? Set MCP_EDITION=editor or admin when launching the container.
• Can I run multiple registries? Yes, define SCHEMA_REGISTRY_NAME_n, SCHEMA_REGISTRY_URL_n, and VIEWONLY_n environment variables (up to 8).
• Is authentication mandatory? No, but can be enabled with ENABLE_AUTH=true and the appropriate OAuth environment variables.
• Where are the Claude Desktop config files? In config-examples/ – copy the one matching your deployment to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/claude-desktop/config.json (Linux).
• How do I upgrade from v2 to v3? Follow the migration guide at docs/v3-migration-guide.md; note the new edition model and deprecated SLIM_MODE alias.
• What language is the server written in? Python 3.10+, packaged as a Docker image.

Kafka Schema Registry MCP Server

A comprehensive Model Context Protocol (MCP) server that provides Claude Desktop and other MCP clients with tools for Kafka Schema Registry operations. Features advanced schema context support, multi-registry management, and comprehensive schema export capabilities.

🎯 True MCP Implementation: Uses FastMCP 4.1+ on MCP Python SDK 2 with MCP 2026-07-28 compliance. The same process negotiates 2025-11-25 with older clients. Fully compatible with Claude Desktop and other MCP clients using JSON-RPC over stdio.

Latest Version: v3.0.0 | Docker: aywengo/kafka-schema-reg-mcp:stable

🎛️ v3.0 editions. The server runs as viewer (read-only: browse, export, compare, compatibility), editor (viewer + schema registration and evolution) or admin (full access: configuration, deletion, migration, bulk operations, disaster recovery). Plain :latest / :stable images are viewer; -editor and -admin tags and the Helm edition value opt into more. SLIM_MODE is a deprecated alias for editor. See docs/editions.md and docs/v3-migration-guide.md.

📋 Table of Contents

• 🚀 Quick Start
• ✨ Key Features
• 🛠️ Claude Code Skills
• 📦 Installation
• ⚙️ Configuration
• 💬 Usage Examples
• 🔒 Authentication & Security
• 📚 Documentation
• 🧪 Testing
• 🚀 Deployment
• 🤝 Contributing
• 🆕 What's New

🚀 Quick Start

1. Run with Docker (Recommended)

# Latest stable release
docker pull aywengo/kafka-schema-reg-mcp:stable

# Viewer is the default; choose editor or admin explicitly when you need writes
docker run -e MCP_EDITION=editor -e SCHEMA_REGISTRY_URL=http://localhost:8081 aywengo/kafka-schema-reg-mcp:stable

# OR run with the full admin surface for administrators/SRE
docker run -e MCP_EDITION=admin -e SCHEMA_REGISTRY_URL=http://localhost:8081 aywengo/kafka-schema-reg-mcp:stable

2. Configure Claude Desktop

Copy a ready-to-use configuration from config-examples/:

# macOS
cp config-examples/claude_desktop_stable_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
cp config-examples/claude_desktop_stable_config.json ~/.config/claude-desktop/config.json

3. Start Using with Claude

Restart Claude Desktop and try these prompts:

• "List all schema contexts"
• "Show me the subjects in the production context"
• "Register a new user schema with fields for id, name, and email"

✨ Key Features

• 🤖 Claude Desktop Integration - Direct MCP integration with natural language interface
• 🏢 Multi-Registry Support - Manage up to 8 Schema Registry instances simultaneously
• 📋 Schema Contexts - Logical grouping for production/staging environment isolation
• 🔄 Schema Migration - Cross-registry migration with backup and verification
• 📊 Comprehensive Export - JSON, Avro IDL formats for backup and documentation
• 🔒 Production Safety - VIEWONLY mode and per-registry access control
• 🔐 OAuth 2.1 Authentication - Enterprise-grade security with scope-based permissions
• 📈 Real-time Progress - Async operations with progress tracking and cancellation
• 🔗 Resource Linking - HATEOAS navigation with enhanced tool responses
• 🧪 MCP 2026-07-28 - FastMCP 4 / MCP SDK 2; one process also serves 2025-11-25 clients
• 🎛️ Three editions - viewer (39 tools), editor (42) and admin (66) from one codebase

📖 See detailed feature descriptions: docs/api-reference.md

🛠️ Claude Code Skills

This project includes 5 specialized Claude Code skills – 4 for automated schema development workflows plus 1 for schema context comparison (/context-compare, documented below):

Available Skills

• /schema-generate - Generate production-ready Avro schemas from natural language

  /schema-generate event UserRegistered "user registration with userId, email, timestamp"
  

• /schema-evolve - Safely evolve schemas with automatic compatibility checking

  /schema-evolve user-profile "add optional phoneNumber field"
  

• /migration-plan - Create detailed migration plans between environments

  /migration-plan development staging
  

• /lint-and-test - Automated quality assurance workflows

  /lint-and-test quick        # Before commit (2-3s)
  /lint-and-test fix          # Auto-fix issues (20-30s)
  /lint-and-test pre-push     # Before push (10-15s)
  

Getting Started with Skills

Quick Start: Read .claude-code/SKILLS_GUIDE.md - 5-minute tutorial

Complete Reference: .claude-code/skills/README.md - Full documentation

Setup Summary: .claude-code/skills/README.md - Configuration details

Skills Features

• ✅ Natural language schema generation with templates
• ✅ Automatic compatibility checking (BACKWARD, FORWARD, FULL)
• ✅ Migration planning with rollback procedures
• ✅ Pre-commit and pre-push quality automation
• ✅ Integration with Black, Ruff, isort, Flake8
• ✅ Docker-based test execution
• ✅ Comprehensive error handling and auto-fix

Try it now: /schema-generate event TestEvent "test with id and timestamp"

📦 Installation

Option A: Docker (Recommended)

# Viewer (default, 39 tools)
docker pull aywengo/kafka-schema-reg-mcp:stable

# Editor (42 tools) and admin (66 tools)
docker pull aywengo/kafka-schema-reg-mcp:stable-editor
docker pull aywengo/kafka-schema-reg-mcp:stable-admin

# Pin the release candidate and edition
docker pull aywengo/kafka-schema-reg-mcp:3.0.0-admin

Choosing an edition

MCP_EDITION selects the tool surface at startup. Plain tags run viewer.

# Read-only browsing
docker run -e SCHEMA_REGISTRY_URL=http://localhost:8081 aywengo/kafka-schema-reg-mcp:stable

# Schema registration and evolution
docker run -e MCP_EDITION=editor -e SCHEMA_REGISTRY_URL=http://localhost:8081 aywengo/kafka-schema-reg-mcp:stable

# Full surface, including deletion and migration
docker run -e MCP_EDITION=admin -e SCHEMA_REGISTRY_URL=http://localhost:8081 aywengo/kafka-schema-reg-mcp:stable

⚠️ SLIM_MODE is deprecated. It is an alias for MCP_EDITION=editor and will be removed in 4.0.0. Do not set both variables.

See docs/editions.md for the complete per-edition tool list and docs/v3-migration-guide.md for the upgrade path.

Option B: Local Python

git clone https://github.com/aywengo/kafka-schema-reg-mcp
cd kafka-schema-reg-mcp
pip install -r requirements.txt
python kafka_schema_registry_unified_mcp.py

Option C: Docker Compose

docker-compose up -d  # Includes Schema Registry for testing

📖 Detailed installation guide: docs/deployment.md

⚙️ Configuration

Single Registry Mode

export SCHEMA_REGISTRY_URL="http://localhost:8081"
export SCHEMA_REGISTRY_USER=""           # Optional
export SCHEMA_REGISTRY_PASSWORD=""       # Optional
export VIEWONLY="false"                  # Production safety
export MCP_EDITION="viewer"              # viewer | editor | admin (default: viewer)

Multi-Registry Mode (Up to 8 Registries)

# Development Registry
export SCHEMA_REGISTRY_NAME_1="development"
export SCHEMA_REGISTRY_URL_1="http://dev-registry:8081"
export VIEWONLY_1="false"

# Production Registry (with safety)
export SCHEMA_REGISTRY_NAME_2="production"
export SCHEMA_REGISTRY_URL_2="http://prod-registry:8081"
export VIEWONLY_2="true"                     # Read-only protection

Claude Desktop Configuration

Pre-configured examples available in config-examples/:

Configuration	Use Case	File
Production	Stable Docker deployment	claude_desktop_stable_config.json
Multi-Environment	DEV/STAGING/PROD registries	claude_desktop_multi_registry_docker.json
Local Development	Python local execution	claude_desktop_config.json
View-Only Safety	Production with safety	claude_desktop_viewonly_config.json

📖 Complete configuration guide: config-examples/README.md

Edition Configuration

An edition decides which tools are registered. Tools outside the active edition are not listed and cannot be called, so they cost no context and cannot be invoked by mistake.

Edition	Tools	Use case
viewer (default)	39	Browse, export, compare, compatibility checks
editor	42	Viewer plus schema registration and evolution
admin	66	Full surface: configuration, deletion, migration, bulk operations

export MCP_EDITION="admin"

Precedence: MCP_EDITION > SLIM_MODE alias > MCP_EDITION_DEFAULT > viewer. Setting MCP_EDITION and SLIM_MODE together is a startup error.

Resources are shared by every edition. Read-only access stays available in viewer through the registry://, schema:// and subject:// resources.

VIEWONLY is enforced at the HTTP session boundary. A read-only registry rejects PUT, DELETE and non-read POST requests even if a write tool is exposed by the edition.

📊 MCP Tools and Resources

The tool surface is generated from tool_catalog.py; the tables in docs/editions.md are generated from the same catalog.

Edition	Tools	Highlights
viewer	39	Registry info, subjects, schemas, compatibility, export, comparison, statistics, resources
editor	+3	register_schema, check_compatibility, interactive schema registration
admin	+26	Configuration, deletion, contexts, migration, bulk operations, workflows

The server also exposes 10 prompts, 4 concrete resources and 17 resource templates. See docs/mcp-tools-reference.md for parameter details.

💬 Usage Examples

Schema Management

# In Claude Desktop, use natural language:
"Register a user schema with id, name, email fields"
"Check if my updated schema is compatible"
"Export all schemas from staging context"
"List subjects in production context"

Multi-Registry Operations

"Compare development and production registries"
"Migrate user-events schema from staging to production"
"Test connections to all registries"
"Show me registry statistics"

Batch Operations

"Clear all schemas from test context"
"Export global schemas for backup"
"Count schemas across all contexts"

📖 More examples: examples/ | 📖 Use cases: docs/use-cases.md

🔒 Authentication & Security

OAuth 2.1 Support (Optional)

# Enable authentication
export ENABLE_AUTH=true
export AUTH_ISSUER_URL="https://your-oauth-provider.com"
export AUTH_AUDIENCE="your-client-id"

Supported Providers: Azure AD, Google OAuth, Keycloak, Okta, GitHub

Permission Scopes:

• read - View schemas, configurations
• write - Register schemas, update configs (includes read)
• admin - Delete subjects, full control (includes write + read)

Production Safety Features

• VIEWONLY Mode - Prevent accidental changes in production
• URL Validation - SSRF protection with configurable localhost access
• Scope-based Authorization - Fine-grained tool-level permissions
• Per-Registry Controls - Independent safety settings

📖 Security guide: docs/deployment.md#security

📚 Documentation

Guide	Description
API Reference	Complete tool documentation with examples
Subject Aliasing	How to add and remove subject aliases
Use Cases	Real-world scenarios and implementation patterns
Deployment Guide	Docker, Kubernetes, cloud platforms, CI/CD
IDE Integration	VS Code, Claude Code, Cursor setup
Configuration Examples	Ready-to-use Claude Desktop configs
Testing Guide	Comprehensive testing setup
Changelog	Version history and migration notes
v2.0.0 Highlights	Major version features

Additional Resources

• Examples - Usage examples and code samples
• Scripts - Utility scripts and automation
• Helm Charts - Kubernetes deployment
• Tests - Test suites and validation

🧪 Testing

Quick Test

cd tests/
./run_all_tests.sh --quick    # Essential tests
./run_all_tests.sh           # Complete test suite

Docker Testing

python tests/test_docker_mcp.py

MCP Inspector Tests (UI-driven)

# From repository root
cd inspector-tests

# Single registry (DEV)
./run-inspector-tests.sh stable

# Multi-registry (DEV + PROD)
./run-inspector-tests.sh multi

# Test a specific Docker tag
DOCKER_VERSION=latest ./run-inspector-tests.sh stable

📖 Testing guide: TESTING_SETUP_GUIDE.md

🚀 Deployment

Production Docker

# With docker-compose
docker-compose up -d

# Direct Docker
docker run -d -p 38000:8000 \
  -e SCHEMA_REGISTRY_URL=http://registry:8081 \
  aywengo/kafka-schema-reg-mcp:stable

Kubernetes

# Using Helm charts
helm install kafka-schema-mcp ./helm/kafka-schema-reg-mcp

📖 Deployment guide: docs/deployment.md

🤝 Contributing

We welcome contributions. Open an issue or pull request on GitHub, and see:

• Development Setup
• Testing Guide
• Release Process

Quick Development Setup

git clone https://github.com/aywengo/kafka-schema-reg-mcp
cd kafka-schema-reg-mcp
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python kafka_schema_registry_unified_mcp.py

🆕 What's New

v3.0.0 (Latest)

• 🎛️ Editions - viewer (39 tools), editor (42) and admin (66) from one image; SLIM_MODE is a deprecated alias for editor
• 📋 MCP 2026-07-28 - Dual-era protocol support with FastMCP native background tasks
• 🔒 FastMCP 4.1+ - Current MCP SDK 2 stack with the 2026 security fixes
• 🧭 MRTR workflows - Guided schema evolution, migration, context reorganisation and disaster recovery
• 🚚 Migration guide - docs/v3-migration-guide.md

v2.1.x

• 🧭 Subject Aliasing - New tools add_subject_alias and delete_subject_alias
• 🛠️ Fixes - Evolution assistant and import interactive fixes
• 📦 Enhancements - Continued MCP tool refinements and testing improvements
• 🗑️ Removed Deprecated Tools - Custom task management tools removed in favor of FastMCP's built-in Docket system

v2.0.x

• 🔒 Security Fixes - Resolved credential exposure in logging
• 🤖 Interactive Schema Migration - Smart migration with user preference elicitation
• 💾 Automatic Backups - Pre-migration backup creation
• ✅ Post-Migration Verification - Comprehensive schema validation
• 🚀 FastMCP 2.8.0+ Framework - Complete architecture upgrade
• 📊 MCP 2025-06-18 Compliance - Protocol version at the time of the v2.0 release
• 🔐 OAuth 2.1 Generic Discovery - Universal provider compatibility
• 🔗 Resource Linking - HATEOAS navigation in tool responses

📖 Full changelog: CHANGELOG.md | 📖 v2.0.0 features: README-v2.0.0-HIGHLIGHTS.md

---

🐳 Glama.ai:

---

🐳 Docker Hub: aywengo/kafka-schema-reg-mcp | 📊 Stats: 39 / 42 / 66 tools by edition, 4 resources + 17 templates, 8 registries, OAuth 2.1, multi-platform

License: MIT | Maintainer: @aywengo | Issues: GitHub Issues