Name: Kafka Schema Reg
Author: aywengo

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 modern FastMCP 2.8.0+ framework with full MCP 2025-06-18 specification compliance. Fully compatible with Claude Desktop and other MCP clients using JSON-RPC over stdio.

Latest Version: v2.1.5 | Docker: aywengo/kafka-schema-reg-mcp:stable

</td> </tr> </table>

🚀 Quick Start

1. Run with Docker (Recommended)

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

# Recommended: Run with SLIM_MODE for optimal performance (reduced essential tool set)
docker run -e SCHEMA_REGISTRY_URL=http://localhost:8081 -e SLIM_MODE=true aywengo/kafka-schema-reg-mcp:stable

# OR run with full feature set for administrators/SRE
docker run -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
🧪 Full MCP Compliance - 50+ tools following MCP 2025-06-18 specification
🚀 SLIM_MODE - Reduce tool overhead from 50+ to ~9 essential tools for better LLM performance

📖 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)

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

# Latest development  
docker pull aywengo/kafka-schema-reg-mcp:latest

# Specific version
docker pull aywengo/kafka-schema-reg-mcp:2.1.3

Running with SLIM_MODE

To reduce LLM overhead, run with SLIM_MODE enabled:

# Run with a reduced essential tool set
docker run -e SCHEMA_REGISTRY_URL=http://localhost:8081 -e SLIM_MODE=true aywengo/kafka-schema-reg-mcp:stable

💡 SLIM_MODE Benefits:

Reduces tool count to an essential subset

Significantly faster LLM response times

Lower token usage and reduced costs

Ideal for production read-only operations

Maintains full remote deployment support

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 SLIM_MODE="false"                 # Optional: Enable to reduce tool overhead (default: false)

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

SLIM_MODE Configuration (Performance Optimization)

SLIM_MODE reduces the number of exposed MCP tools to an essential subset, significantly reducing LLM overhead and improving response times.

💡 Recommendation: SLIM_MODE is recommended for most use cases as it provides all essential schema management capabilities with optimal performance.

When to Use SLIM_MODE (Recommended)

Default choice for most users and day-to-day operations
When experiencing slow LLM responses due to too many tools
For production environments focused on read-only operations
When you only need basic schema management capabilities
To reduce token usage and improve performance

When to Use Non-SLIM Mode

For administrators or SRE teams performing long-running operations
When you need advanced operations like:
- Schema migrations across registries
- Bulk schema removals and cleanup operations
- Complex batch operations and workflows
- Interactive guided wizards for complex tasks
- Comprehensive export/import operations

Enable SLIM_MODE

export SLIM_MODE="true"  # Reduces tools from 50+ to ~9
# Enables reduced essential tool set

Tools Available in SLIM_MODE

Essential Read-Only Tools:

ping - Server health check
set_default_registry, get_default_registry - Registry management
count_contexts, count_schemas, count_schema_versions - Statistics

Basic Write Operations:

register_schema - Register new schemas
check_compatibility - Schema compatibility checking
create_context - Create new contexts

Essential Export Operations:

export_schema - Export single schema
export_subject - Export all subject versions

Resources Available (All Modes):

All 19 resources remain available in SLIM_MODE
registry://, schema://, subject:// resource URIs
Full read access through resource-first approach

Tools Hidden in SLIM_MODE:

All migration tools (migrate_schema, migrate_context)
All batch operations (clear_context_batch)
Advanced export/import tools (export_context, export_global)
All interactive/elicitation tools (*_interactive variants)
Heavy statistics tools with async operations
Workflow tools
Configuration update tools
Delete operations

Note: Task status tracking is now handled by FastMCP's built-in Docket system. Custom task management tools have been removed in favor of FastMCP's native task tracking.

Note: You can switch between mo

…

Kafka Schema Reg

Installation

Configuration

How to use

README