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.
Latest Version: v3.2.0 | Docker: |
ποΈ v3.0 editions. The server runs as
viewer(read-only: browse, export, compare, compatibility),editor(viewer + schema registration and evolution) oradmin(full access: configuration, deletion, migration, bulk operations, disaster recovery). Plain:latest/:stableimages areviewer;-editorand-admintags and the Helmeditionvalue opt into more.SLIM_MODEis a deprecated alias foreditor. See docs/editions.md and docs/v3-migration-guide.md.
- π Quick Start
- β¨ Key Features
- π οΈ Claude Code Skills
- π¦ Installation
- βοΈ Configuration
- π¬ Usage Examples
- π Authentication & Security
- π Documentation
- π§ͺ Testing
- π Deployment
- π€ Contributing
- π What's New
# 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:stableCopy 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.jsonRestart 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"
- π€ 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
- π©Ί Registry Insights -
get_registry_insightsreports version spread, schema types, compatibility overrides, dangling references and findings such asCOMPATIBILITY_NONE - π Resource Linking - HATEOAS navigation with enhanced tool responses
- π§ͺ MCP 2026-07-28 - FastMCP 4 / MCP SDK 2; one process also serves
2025-11-25clients - ποΈ Three editions -
viewer(40 tools),editor(43) andadmin(68) from one codebase
π See detailed feature descriptions: docs/api-reference.md
This project includes 5 specialized Claude Code skills β 4 for automated schema development workflows plus 1 for schema context comparison (/context-compare, documented below):
-
/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)
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
- β 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"
# Promoted channel. `:stable` moves only when Tag as Stable runs.
docker pull aywengo/kafka-schema-reg-mcp:stable
docker pull aywengo/kafka-schema-reg-mcp:stable-editor
docker pull aywengo/kafka-schema-reg-mcp:stable-admin
# This release. Admin on the 3.2.0 tag is 68 tools.
docker pull aywengo/kafka-schema-reg-mcp:3.2.0-adminMCP_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_MODEis deprecated. It is an alias forMCP_EDITION=editorand 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.
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.pydocker-compose up -d # Includes Schema Registry for testingπ Detailed installation guide: docs/deployment.md
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)# 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 protectionPre-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
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) |
40 | Browse, export, compare, compatibility checks |
editor |
43 | Viewer plus schema registration and evolution |
admin |
68 | 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.
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 |
40 | Registry info, subjects, schemas, compatibility, export, comparison, statistics and insights, 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 18 resource templates. See docs/mcp-tools-reference.md for parameter details.
# 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""Compare development and production registries"
"Migrate user-events schema from staging to production"
"Test connections to all registries"
"Show me registry statistics""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
# 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, configurationswrite- Register schemas, update configs (includes read)admin- Delete subjects, full control (includes write + read)
- 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
| 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 |
- Examples - Usage examples and code samples
- Scripts - Utility scripts and automation
- Helm Charts - Kubernetes deployment
- Tests - Test suites and validation
cd tests/
./run_all_tests.sh --quick # Essential tests
./run_all_tests.sh # Complete test suitepython tests/test_docker_mcp.py# 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
# 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# Using Helm charts
helm install kafka-schema-mcp ./helm/kafka-schema-reg-mcpπ Deployment guide: docs/deployment.md
We welcome contributions. The contribution guide covers
branching from main, lint, and tests. Also see:
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- π©Ί Registry insights -
get_registry_insights(viewer) reports version spread, schema types, compatibility overrides, dangling references and findings. Editions are now 40 / 43 / 68 tools - π‘οΈ DR objectives -
guided_disaster_recoverytakes RPO, RTO and scenarios, picks the backup cadence and recovery path, and returns a Markdown runbook - π Trace continuation - HTTP
traceparentandtracestatecontinue into the tool span; setOTEL_EXPORTER_OTLP_ENDPOINTto export
- β»οΈ Restore -
restore_bundleapplies an export document to one registry, dry-run unless told to write, and preserves schema ids. Admin is now 67 tools - π One verifier - Human, client-credentials, and SEP-990 access tokens share one check. Grants are advertised only when the issuer lists them
- π’ Fleet front - Optional process that routes
registry=to a shard and holds no registry password - β±οΈ Cache hints - Per-resource
ttlMs, includingschema://{name}/ids/{schema_id}(24 h)
- ποΈ Editions -
viewer(39 tools),editor(42) andadmin(66) from one image;SLIM_MODEis a deprecated alias foreditor - π 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
- π§ Subject Aliasing - New tools
add_subject_aliasanddelete_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
- π 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: 40 / 43 / 68 tools by edition, 4 resources + 18 templates, 8 registries, OAuth 2.1, multi-platform
License: MIT | Maintainer: @aywengo | Issues: GitHub Issues
