Kafka Schema Registry MCP Server

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