MCP Config Converter

A configuration converter for the Model Context Protocol (MCP) with an enhanced CLI experience.

The Model Context Protocol (MCP) is a standardized protocol for communication between LLM applications and external context providers. As MCP adoption grows across different LLM providers and development environments, each platform has developed its own configuration format and conventions for defining MCP servers.

This project was created to address the challenges developers face when working with MCP configurations across multiple platforms:

• Fragmented Ecosystem: Different LLM providers (Claude, Gemini, etc.) and development environments (VS Code, OpenCode) use different configuration formats for MCP servers

• Manual Conversion: Developers often need to manually rewrite configurations when switching between platforms or sharing MCP server setups

• Configuration Complexity: MCP server configurations can include commands, arguments, environment variables, and metadata that need to be carefully preserved during conversion

• Lack of Standardization: While MCP itself is standardized, configuration formats are not, leading to compatibility issues

• Subjective Tool Preference: Developers and teams have varying preferences for coding assistants and CLIs. This tool is intentionally tool-agnostic and works seamlessly across all major LLM platforms and coding environments, including when accessed via different CLIs.

What This Tool Enables

mcp-config-converter provides a unified tool to:

Core Capabilities:

1. Parse Multiple Formats: Read MCP configurations from JSON, YAML, and TOML files

2. Convert Between Providers: Transform configurations between different LLM provider formats (Claude, Gemini, VS Code, OpenCode)

3. Preserve Semantics: Maintain all configuration details including commands, arguments, environment variables, and metadata

4. Validate Configurations: Ensure MCP configurations are well-formed and complete

5. Streamline Workflows: Enable easy sharing and reuse of MCP server configurations across different platforms

Practical Use Cases:

• Cross-platform Development: Develop MCP servers that work across multiple LLM platforms
• Configuration Sharing: Share MCP server setups with teams using different tools
• Migration: Move MCP configurations when switching between LLM providers
• Standardization: Maintain a single source of truth for MCP configurations in your preferred format

• 🔄 Multi-format Support: Parse and generate JSON, YAML, and TOML configurations

• 🎯 Provider-specific Formatting: Output configurations optimized for Claude, Gemini, VS Code, OpenCode, and AI-assisted conversion with multiple LLM providers (OpenAI, Ollama, DeepSeek, SambaNova, Perplexity, OpenRouter)

• 🔀 Intelligent File Merging: Format-agnostic merge options (update, replace, overwrite, skip) for JSON, YAML, and TOML configurations

• ✅ Validation: Validate MCP configurations against to protocol schema

• 🎨 Rich CLI Experience: User-friendly command-line interface with colorful output powered by Rich and Typer

• 🔧 Extensible Architecture: Easy to add support for new formats and providers

• 🤖 Unified LLM Support: Built on LiteLLM, providing access to 100+ LLM providers through a single unified interface with automatic retry logic and exponential backoff

This project uses LiteLLM as a unified interface to support 100+ LLM providers. The LiteLLM integration provides:

• Single Unified API: One consistent interface for all LLM providers

• Automatic Retry Logic: Built-in retry mechanism with exponential backoff for rate limits and service unavailability

• Smart Model Mapping: Friendly model names automatically mapped to provider-specific identifiers

• Flexible Configuration: Support for API keys via environment variables or direct parameters

The tool supports all major LLM providers through LiteLLM. When no model is specified, the tool uses the following hard-coded default model:

Note: The providers listed above are those that have been tested and integrated with this tool. Other providers are available via LiteLLM's great unified interface. The default model listed above is the hard-coded fallback used when no other model is specified.

The tool supports automatic provider selection based on cost:

# Auto-select cheapest available provider (prefers ollama, then zai, etc.)
uv run mcp-config-converter convert config.yaml --preferred-provider auto --output output.json

# Use specific provider
uv run mcp-config-converter convert config.yaml --preferred-provider openai --output output.json

Provider Cost Priorities (cheapest to most expensive):

Note: Costs are estimates based on typical pricing per 1M tokens. Actual costs vary by usage patterns.

Overriding Cost Factors:

You can override default cost factors via environment variables (case-insensitive):

# Example: Override ollama cost to 10 (useful if it's slow)
export MCP_CONVERT_CONF_OLLAMA_COST=10

# Example: Make deepseek more expensive than default
export MCP_CONVERT_CONF_DEEPSEEK_COST=100

# Example: Override multiple providers
export MCP_CONVERT_CONF_OPENAI_COST=95
export MCP_CONVERT_CONF_ANTHROPIC_COST=85

Cost Override Rules:

• Values must be positive integers
• Values > 100 are allowed
• Negative values are ignored with warning (uses default)
• Non-integer values are ignored with warning (uses default)

This project uses uv for dependency management and supports multiple installation methods:

# Clone repository
git clone https://github.com/yourusername/mcp-config-converter.git
cd mcp-config-converter

# Install using uv (recommended for Python projects)
uv sync

# Or install using pip
pip install mcp-config-converter

# Or use uvx to run directly without installation
uvx --from git+https://github.com/yourusername/mcp-config-converter run mcp-config-converter convert ...

Note: With a unified LiteLLM implementation, all LLM providers are now supported out of the box without additional optional dependencies. Simply set the appropriate API key environment variable for your chosen provider.

The tool supports loading API keys and configuration from a .env file. This allows you to securely manage your LLM provider credentials without hardcoding them.

1. Copy example file:

cp .env.example .env

2. Edit .env file and add your API keys:

# OpenAI API Key
OPENAI_API_KEY=your_openai_api_key_here

# Anthropic (Claude) API Key
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Google Gemini API Key
GOOGLE_API_KEY=your_google_api_key_here

# Other providers...

Note: The .env file is automatically loaded** when running tests or the CLI tool, so you don't need to manually set environment variables.

Note: Never commit your .env file with real API keys! It's already excluded in .gitignore.

Default output paths for converted configurations can be overridden via environment variables. This allows you to customize where converted files are saved without specifying the --output option each time.

• Provider-specific: MCP_CONFIG_CONV_<PROVIDER>_DEFAULT_OUTPUT
• Generic fallback: MCP_CONFIG_CONV_DEFAULT_OUTPUT (applies to all providers)

Supported providers include: VSCODE, GEMINI, CLAUDE, CODEX, OPENCODE, MISTRAL, QWEN, LLXPRT, CRUSH

# Override VS Code default output path
export MCP_CONFIG_CONV_VSCODE_DEFAULT_OUTPUT=".vscode/custom-mcp.json"

# Override generic default for all providers
export MCP_CONFIG_CONV_DEFAULT_OUTPUT="custom-output.json"

# View current defaults and overrides
uv run mcp-config-converter show-defaults

The show-defaults command displays a table showing:

• Default output path for each provider
• Environment variable name for overriding
• Current override value (if set)
• Whether the provider is an alias of another

1. Provider-specific environment variable (e.g., MCP_CONFIG_CONV_VSCODE_DEFAULT_OUTPUT)
2. Generic environment variable (MCP_CONFIG_CONV_DEFAULT_OUTPUT)
3. Built-in default path

The tool includes a disk caching feature for LLM responses to reduce API calls and improve conversion speed when processing the same configuration multiple times.

• Reduced API Costs: Cache responses avoid redundant API calls for identical conversions

• Faster Iterations: Subsequent conversions of the same configuration are nearly instant

• Offline Development: Work with cached responses when API access is unavailable

Enable caching by setting the MCP_CONFIG_CONF_LLM_CACHE_ENABLED environment variable:

# Enable caching
export MCP_CONFIG_CONF_LLM_CACHE_ENABLED=true

# Now conversions will use cached responses when available
uv run mcp-config-converter convert config.yaml --provider claude --output output.json

Alternatively, enable caching per-command using the --enable-cache flag:

uv run mcp-config-converter convert config.yaml --provider claude --output output.json --enable-cache

By default, cache files are stored in .litellm_cache in the project root. You can specify a custom cache directory using the --cache-dir option:

# Use a custom cache directory
uv run mcp-config-converter convert config.yaml --provider claude --output output.json --enable-cache --cache-dir /path/to/custom/cache

# Or set an environment variable
export MCP_CONFIG_CONF_LLM_CACHE_DIR=/path/to/custom/cache

uv run mcp-config-converter convert config.yaml --provider claude --output output.json --enable-cache

# Enable cache via environment variable and run conversion
export MCP_CONFIG_CONF_LLM_CACHE_ENABLED=true
uv run mcp-config-converter convert config.yaml --provider vscode --output .vscode/mcp.json

# Enable cache via CLI flag
uv run mcp-config-converter convert config.yaml --provider gemini --output gemini_mcp.json --enable-cache

# Use custom cache directory
uv run mcp-config-converter convert config.yaml --provider claude --output claude_mcp.json --enable-cache --cache-dir ~/.mcp-cache

The default .litellm_cache directory is included in .gitignore to prevent accidentally committing cached responses to version control. If using a custom cache directory, ensure it's also excluded from your version control system.

The test suite can be configured via environment variables:

| Variable | Purpose | Default | Example | |----------|----------|----------| | MCP_CONFIG_CONF_MAX_TESTS | Maximum successful conversions per output provider | 2 | export MCP_CONFIG_CONF_MAX_TESTS=5 | | MCP_CONFIG_CONF_TEST_LLM_PROVIDERS | Specific LLM providers to test | ollama/-1 | export MCP_CONFIG_CONF_TEST_LLM_PROVIDERS="deepseek/deepseek-chat,openrouter/model" |

Example Usage:

# Test with default (ollama, 2 tests per provider)
uv run pytest tests/test_cli.py

# Test with specific providers (5 tests per provider)
export MCP_CONFIG_CONF_TEST_LLM_PROVIDERS="deepseek/deepseek-chat,openrouter/xiaomi/mimo-v2-flash:free,zai/glm-4.7"
export MCP_CONFIG_CONF_MAX_TESTS=5
uv run pytest tests/test_cli.py

# Single provider test
export MCP_CONFIG_CONF_TEST_LLM_PROVIDERS="openai/gpt-4o-mini"
uv run pytest tests/test_cli.py

• Single: provider/model (e.g., openrouter/subprovider/model)
• List: Comma, semicolon, or colon-separated (e.g., ollama/gemma3, deepseek/deepseek-chat; sambanova/model)
• Provider only: Uses model index -1 (last model)

• Parsing failures cause test suite to fail immediately
• Missing API keys cause test suite to fail
• Invalid providers cause client instantiation to fail

# Convert an MCP configuration file to Claude format using LiteLLM with Ollama (local, no API key)
uv run mcp-config-converter convert config.yaml --provider claude --output claude_config.json --preferred-provider litellm --llm-model ollama/llama2

# Convert using LiteLLM with GPT-4
uv run mcp-config-converter convert config.yaml --provider claude --output output.json --preferred-provider litellm --llm-model gpt-4

# Convert using LiteLLM with Claude (requires ANTHROPIC_API_KEY)
uv run mcp-config-converter convert config.yaml --provider vscode --output output.json --preferred-provider litellm --llm-model claude-3.5-sonnet-20241022

# Use auto provider selection (picks best available provider)
uv run mcp-config-converter convert config.yaml --provider claude --output output.json --preferred-provider auto

# Check LLM provider status
uv run mcp-config-converter llm-check

mcp-config-converter/
├── mcp_config_converter/
│   ├── cli/                # Command-line interface modules
│   │   ├── arguments.py    # CLI argument parsing
│   │   ├── convert.py     # Convert command implementation
│   │   ├── llm_check.py   # LLM provider checking
│   │   ├── validate.py     # Validation command implementation
│   │   └── ...            # Other CLI modules
│   ├── llm/               # LLM provider implementations
│   │   ├── base.py        # Base LLM interface
│   │   ├── claude.py      # Claude provider
│   │   ├── deepseek.py    # DeepSeek provider
│   │   └── ...            # Other LLM providers
│   ├── prompts/           # LLM prompt templates
│   ├── specs/             # MCP provider specifications
│   ├── transformers.py     # Configuration transformation logic
│   ├── types.py           # Type definitions
│   └── utils.py           # Utility functions
└── tests/                 # Test suite

Contributions are welcome!

This project aims to support the growing MCP ecosystem by making configurations portable and accessible across platforms.

MIT License - see LICENSE file for details.

This project supports the Model Context Protocol ecosystem and aims to improve interoperability between different MCP implementations.

This project builds on LiteLLM's great unified interface for 100+ LLM providers.