jr2804/mcp-config-converter

Latest recorded source activity: January 21, 2026 at 23:55

SkillsMP catalog refreshed: November 2, 2026 at 18:02

skills collected: 17

GitHub stars: 4
GitHub forks: 1

Install with an AI assistant

Copy this prompt into the AI assistant you're using.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/jr2804/mcp-config-converter.

Repository README

Repository README source: README.md

Read the source README

Expand full README

# MCP Config Converter A configuration converter for the Model Context Protocol (MCP) with an enhanced CLI experience. ## Background 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. ## Motivation This project was created to address the challenges developers face when working with MCP configurations across multiple platforms: ### The Problem - **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 1. **Convert Between Providers**: Transform configurations between different LLM provider formats (Claude, Gemini, VS Code, OpenCode) 1. **Preserve Semantics**: Maintain all configuration details including commands, arguments, environment variables, and metadata 1. **Validate Configurations**: Ensure MCP configurations are well-formed and complete 1. **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 ## Key Features - 🔄 **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](https://github.com/BerriAI/litellm), providing access to 100+ LLM providers through a single unified interface with automatic retry logic and exponential backoff ## LLM Provider Support 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 ### Supported Providers & Models The tool supports all major LLM providers through LiteLLM. When no model is specified, the tool uses the following hard-coded default model: | Provider | Environment Variable | Default Model | | ---------- | ---------------- | ------------- | | **OpenAI** | `OPENAI_API_KEY` | `gpt-4o-mini` | | **Anthropic (Claude)** | `ANTHROPIC_API_KEY` | `claude-3-5-sonnet-20241022` | | **Google Gemini** | `GOOGLE_API_KEY`, `GEMINI_API_KEY` | `gemini-3-flash-preview` | | **Vertex AI** | `GOOGLE_APPLICATION_CREDENTIALS` | `gemini-2.0-flash-exp` | | **Ollama** | None (local) | First available model | | **Mistral** | `MISTRAL_API_KEY` | `mistral-medium-latest` | | **DeepSeek** | `DEEPSEEK_API_KEY` | `deepseek-chat` | | **OpenRouter** | `OPENROUTER_API_KEY` | `xiaomi/mimo-v2-flash:free` | | **Perplexity** | `PERPLEXITY_API_KEY` | `sonar` | | **Poe** | `POE_API_KEY` | `gemini-2.5-flash-lite` | | **SambaNova** | `SAMBANOVA_API_KEY` | `Meta-Llama-3.1-8B-Instruct` | | **z.ai** | `ZAI_API_KEY` | Various models | | **Cohere** | `COHERE_API_KEY` | `command` | > **Note**: The providers listed above are those that have been tested and integrated with this tool. Other providers are available via [LiteLLM](https://www.litellm.ai/)'s great unified interface. The default model listed above is the hard-coded fallback used when no other model is specified. ### Using LiteLLM Provider The tool supports automatic provider selection based on cost: ```bash # 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):** | Cost | Provider | Notes | |------|-----------|-------| | 0 | **ollama** | Local, no API cost | | 15 | **z.ai** | Very cheap Chinese provider | | 20 | **deepseek** | Very cheap Chinese provider | | 25 | **openrouter** | Cheap aggregation with free tiers | | 30 | **sambanova** | Cheap cloud provider | | 50 | **perplexity** | Moderate cost | | 55 | **gemini** | Moderate cost | | 60 | **mistral** | Moderate+ cost | | 65 | **poe** | Moderate+ cost | | 80 | **cohere** | Expensive | | 90 | **openai** | Very expensive | | 95 | **anthropic** | Very expensive | | 100 | **vertex_ai** | 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): ```bash # 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) ## Installation This project uses `uv` for dependency management and supports multiple installation methods: ### Installation Methods ```bash # 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. ### Environment Configuration 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:** ```bash cp .env.example .env ``` **2. Edit `.env` file** and add your API keys: ```env # 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 Path Configuration 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. #### Environment Variable Format - **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` #### Example Usage ```bash # 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 #### Priority Order 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 ## Disk Caching 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. ### Benefits - **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 ### Enabling Cache #### Environment Variable Enable caching by setting the `MCP_CONFIG_CONF_LLM_CACHE_ENABLED` environment variable: ```bash # 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 ``` #### CLI Flag Alternatively, enable caching per-command using the `--enable-cache` flag: ```bash uv run mcp-config-converter convert config.yaml --provider claude --output output.json --enable-cache ``` ### Cache Directory 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: ```bash # 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 ``` ### Example Usage ```bash # 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 ``` ### Important Note 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. ## Test Configuration 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:** ```bash # 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 ``` ### Provider/Model Format - 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) ### Error Behavior - Parsing failures cause test suite to fail immediately - Missing API keys cause test suite to fail - Invalid providers cause client instantiation to fail ## Quick Start ### Quick Usage ```bash # 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 ``` ## Project Structure ```text 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 ``` ## Contributing Contributions are welcome! This project aims to support the growing MCP ecosystem by making configurations portable and accessible across platforms. ## License MIT License - see [LICENSE](LICENSE) file for details. ## Acknowledgments This project supports the Model Context Protocol ecosystem and aims to improve interoperability between different MCP implementations. This project builds on [LiteLLM](https://www.litellm.ai/)'s great unified interface for 100+ LLM providers.

Loading the repository README…

Skills in this repository