icon for mcp server

Kafka Schema Registry

STDIO

MCP server for Kafka Schema Registry operations with multi-registry and context management capabilities.

MseeP.ai Security Assessment Badge License: MIT Python Version Docker Pulls GitHub Release GitHub Issues Docker Image Size Maintained MCP Specification

Trust Score

Kafka Schema Registry MCP Server

A comprehensive Message Control 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.

Kafka Schema Registry MCP Logo

🎯 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.0.7 | Docker: aywengo/kafka-schema-reg-mcp:stable

📋 Table of Contents

🚀 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 (~9 tools)
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 (57+ tools) 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 - 57+ tools following MCP 2025-06-18 specification
  • 🚀 SLIM_MODE - Reduce tool overhead from 57+ to ~9 essential tools for better LLM performance

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

📦 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.0.7

Running with SLIM_MODE

To reduce LLM overhead, run with SLIM_MODE enabled:

# Run with ~9 essential tools instead of 57+
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 from 53+ to ~15 essential tools
  • 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/:

ConfigurationUse CaseFile
ProductionStable Docker deploymentclaude_desktop_stable_config.json
Multi-EnvironmentDEV/STAGING/PROD registriesclaude_desktop_multi_registry_docker.json
Local DevelopmentPython local executionclaude_desktop_config.json
View-Only SafetyProduction with safetyclaude_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 from 57+ to ~9 essential tools, 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 57+ to ~9

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
  • Task management and workflow tools
  • Configuration update tools
  • Delete operations

Note: You can switch between modes by restarting with SLIM_MODE=false to access all 57+ tools.

📊 MCP Tools and Resources

This section provides a comprehensive analysis of all MCP tools and resources exposed by the Kafka Schema Registry MCP Server.

Backward Compatibility Wrapper Tools

These tools are maintained for backward compatibility with existing clients. They internally use efficient implementations but are exposed as tools to prevent "Tool not listed" errors. Consider migrating to the corresponding resources for better performance.

Tool NameSLIM_MODEScopeRecommended ResourceDescription
list_registries✅readregistry://namesList all configured registries
get_registry_info✅readregistry://info/{name}Get registry information
test_registry_connection✅readregistry://status/{name}Test registry connection
test_all_registries✅readregistry://statusTest all registry connections
list_subjects✅readregistry://{name}/subjectsList all subjects
get_schema✅readschema://{name}/{context}/{subject}Get schema content
get_schema_versions✅readschema://{name}/{context}/{subject}/versionsGet schema versions
get_global_config✅readregistry://{name}/configGet global configuration
get_mode✅readregistry://modeGet registry mode
list_contexts✅readregistry://{name}/contextsList all contexts
get_subject_config✅readsubject://{name}/{context}/{subject}/configGet subject configuration
get_subject_mode✅readsubject://{name}/{context}/{subject}/modeGet subject mode

Core MCP Tools

CategoryNameTypeSLIM_MODEScopeDescription
CorepingTool✅readMCP ping/pong health check
Registry Managementset_default_registryTool✅adminSet default registry
Registry Managementget_default_registryTool✅readGet current default registry
Schema Operationsregister_schemaTool✅writeRegister new schema version
Schema Operationscheck_compatibilityTool✅readCheck schema compatibility
Context Managementcreate_contextTool✅writeCreate new context
Context Managementdelete_contextTool❌adminDelete context
Subject Managementdelete_subjectTool❌adminDelete subject and versions
Configurationupdate_global_configTool❌adminUpdate global configuration
Configurationupdate_subject_configTool❌adminUpdate subject configuration
Mode Managementupdate_modeTool❌adminUpdate registry mode
Mode Managementupdate_subject_modeTool❌adminUpdate subject mode
Statisticscount_contextsTool✅readCount contexts
Statisticscount_schemasTool✅readCount schemas
Statisticscount_schema_versionsTool✅readCount schema versions
Statisticsget_registry_statisticsTool❌readGet comprehensive registry stats
Exportexport_schemaTool✅readExport single schema
Exportexport_subjectTool✅readExport all subject versions
Exportexport_contextTool❌readExport all context subjects
Exportexport_globalTool❌readExport all contexts/schemas
Exportexport_global_interactiveTool❌readInteractive global export
Migrationmigrate_schemaTool❌adminMigrate schema between registries
Migrationmigrate_contextTool❌adminMigrate context between registries
Migrationmigrate_context_interactiveTool❌adminInteractive context migration
Migrationlist_migrationsTool❌readList migration tasks
Migrationget_migration_statusTool❌readGet migration status
Comparisoncompare_registriesTool❌readCompare two registries
Comparisoncompare_contexts_across_registriesTool❌readCompare contexts across registries
Comparisonfind_missing_schemasTool❌readFind missing schemas
Batch Operationsclear_context_batchTool❌adminClear context with batch operations
Batch Operationsclear_multiple_contexts_batchTool❌adminClear multiple contexts
Interactiveregister_schema_interactiveTool❌writeInteractive schema registration
Interactivecheck_compatibility_interactiveTool❌readInteractive compatibility check
Interactivecreate_context_interactiveTool❌writeInteractive context creation
Resource Discoverylist_available_resourcesTool✅readList all available resources
Resource Discoverysuggest_resource_for_toolTool✅readGet resource migration suggestions
Resource Discoverygenerate_resource_templatesTool✅readGenerate resource URI templates
Task Managementget_task_statusTool❌readGet task status
Task Managementget_task_progressTool❌readGet task progress
Task Managementlist_active_tasksTool❌readList active tasks
Task Managementcancel_taskTool❌adminCancel running task
Task Managementlist_statistics_tasksTool❌readList statistics tasks
Task Managementget_statistics_task_progressTool❌readGet statistics task progress
Elicitationsubmit_elicitation_responseTool❌writeSubmit elicitation response
Elicitationlist_elicitation_requestsTool❌readList elicitation requests
Elicitationget_elicitation_requestTool❌readGet elicitation request details
Elicitationcancel_elicitation_requestTool❌adminCancel elicitation request
Elicitationget_elicitation_statusTool❌readGet elicitation system status
Workflowslist_available_workflowsTool❌readList available workflows
Workflowsget_workflow_statusTool❌readGet workflow status
Workflowsguided_schema_migrationTool❌adminStart schema migration wizard
Workflowsguided_context_reorganizationTool❌adminStart context reorganization wizard
Workflowsguided_disaster_recoveryTool❌adminStart disaster recovery wizard
Utilityget_mcp_compliance_status_toolTool❌readGet MCP compliance status
Utilityget_oauth_scopes_info_toolTool❌readGet OAuth scopes information
Utilitytest_oauth_discovery_endpointsTool❌readTest OAuth discovery endpoints
Utilityget_operation_info_toolTool❌readGet operation metadata
Utilitycheck_viewonly_modeTool❌readCheck if registry is in viewonly mode
RESOURCESregistry://statusResource✅readOverall registry connection status
RESOURCESregistry://infoResource✅readDetailed server configuration
RESOURCESregistry://modeResource✅readRegistry mode detection
RESOURCESregistry://namesResource✅readList of configured registry names
RESOURCESregistry://status/{name}Resource✅readSpecific registry connection status
RESOURCESregistry://info/{name}Resource✅readSpecific registry configuration
RESOURCESregistry://mode/{name}Resource✅readSpecific registry mode
RESOURCESregistry://{name}/subjectsResource✅readList subjects for registry
RESOURCESregistry://{name}/contextsResource✅readList contexts for registry
RESOURCESregistry://{name}/configResource✅readGlobal config for registry
RESOURCESschema://{name}/{context}/{subject}Resource✅readSchema content with context
RESOURCESschema://{name}/{subject}Resource✅readSchema content default context
RESOURCESschema://{name}/{context}/{subject}/versionsResource✅readSchema versions with context
RESOURCESschema://{name}/{subject}/versionsResource✅readSchema versions default context
RESOURCESsubject://{name}/{context}/{subject}/configResource✅readSubject config with context
RESOURCESsubject://{name}/{subject}/configResource✅readSubject config default context
RESOURCESsubject://{name}/{context}/{subject}/modeResource✅readSubject mode with context
RESOURCESsubject://{name}/{subject}/modeResource✅readSubject mode default context
RESOURCESelicitation://response/{request_id}Resource❌writeElicitation response handling

💬 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

GuideDescription
API ReferenceComplete tool documentation with examples
Use CasesReal-world scenarios and implementation patterns
Deployment GuideDocker, Kubernetes, cloud platforms, CI/CD
IDE IntegrationVS Code, Claude Code, Cursor setup
Configuration ExamplesReady-to-use Claude Desktop configs
Testing GuideComprehensive testing setup
ChangelogVersion history and migration notes
v2.0.0 HighlightsMajor 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! Please see:

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

v2.0.x (Latest)

  • 🔒 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 - Latest protocol specification
  • 🔐 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: 70+ MCP Tools (12 backward compatibility), 19 Resources, 8 Registries, OAuth 2.1, Multi-platform

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

Be the First to Experience MCP Now