{"id":35094227,"url":"https://github.com/d-kimuson/modular-mcp","last_synced_at":"2026-03-03T03:06:26.537Z","repository":{"id":320223010,"uuid":"1081258077","full_name":"d-kimuson/modular-mcp","owner":"d-kimuson","description":"A Model Context Protocol (MCP) proxy server that enables efficient management of large tool collections across multiple MCP servers by grouping them and loading tool schemas on-demand.","archived":false,"fork":false,"pushed_at":"2025-11-15T16:28:59.000Z","size":134,"stargazers_count":23,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-15T17:32:02.684Z","etag":null,"topics":["claude","claude-code","codex","llm","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/d-kimuson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-22T14:25:46.000Z","updated_at":"2025-11-15T16:29:03.000Z","dependencies_parsed_at":"2025-10-22T17:31:01.233Z","dependency_job_id":"1e06e087-4be0-4500-a90b-99e91248c6b2","html_url":"https://github.com/d-kimuson/modular-mcp","commit_stats":null,"previous_names":["d-kimuson/modular-mcp"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/d-kimuson/modular-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-kimuson%2Fmodular-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-kimuson%2Fmodular-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-kimuson%2Fmodular-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-kimuson%2Fmodular-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/d-kimuson","download_url":"https://codeload.github.com/d-kimuson/modular-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/d-kimuson%2Fmodular-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28234562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-07T02:00:05.975Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","codex","llm","mcp","mcp-server"],"created_at":"2025-12-27T15:04:24.313Z","updated_at":"2026-01-07T10:03:01.995Z","avatar_url":"https://github.com/d-kimuson.png","language":"TypeScript","funding_links":[],"categories":["📚 Projects (1974 total)"],"sub_categories":["MCP Servers"],"readme":"# Modular MCP\n\n[![License](https://img.shields.io/github/license/d-kimuson/modular-mcp)](https://github.com/d-kimuson/modular-mcp/blob/main/LICENSE)\n[![CI](https://github.com/d-kimuson/modular-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/d-kimuson/modular-mcp/actions/workflows/ci.yml)\n[![GitHub Release](https://img.shields.io/github/v/release/d-kimuson/modular-mcp)](https://github.com/d-kimuson/modular-mcp/releases)\n[![DeepWiki](https://img.shields.io/badge/DeepWiki-d--kimuson%2Fmodular--mcp-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/d-kimuson/modular-mcp)\n\u003c!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ --\u003e\n\nA Model Context Protocol (MCP) proxy server that enables efficient management of large tool collections across multiple MCP servers by grouping them and loading tool schemas on-demand.\n\n## Concept\n\nTraditional MCP setups can overwhelm LLM context when dealing with numerous tools from multiple servers. Modular MCP solves this by:\n\n- **Context Efficiency**: Group information is embedded in tool descriptions, so LLMs can discover available groups without making any tool calls\n- **On-Demand Loading**: Retrieves detailed tool schemas only when needed for specific groups\n- **Separation of Concerns**: Maintains clear phases between tool discovery and execution\n- **Proxy Architecture**: Acts as a single MCP endpoint that manages multiple upstream MCP servers\n\n## How it works?\n\n### 1. Configuration\n\nCreate a configuration file (e.g., `modular-mcp.json`) for the upstream MCP servers you want to manage. This uses the standard MCP server configuration format, with one addition: a `description` field for each server.\n\nHere's an example using Context7 and Playwright MCP servers:\n\n```diff\n{\n+ \"$schema\": \"https://raw.githubusercontent.com/d-kimuson/modular-mcp/refs/heads/main/config-schema.json\",\n  \"mcpServers\": {\n    \"context7\": {\n+     \"description\": \"Use when you need to search library documentation.\",\n-     \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@upstash/context7-mcp@latest\"],\n      \"env\": {}\n    },\n    \"playwright\": {\n+     \"description\": \"Use when you need to control or automate web browsers.\",\n-     \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@playwright/mcp@latest\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\nThe `description` field is the only extension to the standard MCP configuration. It helps the LLM understand each tool group's purpose without loading detailed tool schemas.\n\n**Note**: The `type` field defaults to `\"stdio\"` if not specified. For `stdio` type servers, you can omit the `type` field for cleaner configuration.\n\n#### Environment Variable Interpolation\n\nModular MCP supports environment variable interpolation in configuration files, allowing you to avoid committing sensitive information like API keys and tokens to version control.\n\n**Supported syntax**:\n- `${VAR}` - Braced variable reference\n\n**Note**: Only the `${VAR}` syntax is supported. The `$VAR` syntax (without braces) is intentionally not supported to avoid conflicts with values that legitimately contain dollar signs (e.g., tokens like `token$abc123`).\n\n**Where interpolation is supported**:\n- `stdio` servers: `args` array elements and `env` object values\n- `http`/`sse` servers: `url` string and `headers` object values\n\n**Example**:\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"description\": \"Example server with environment variables\",\n      \"command\": \"node\",\n      \"args\": [\"${HOME}/.local/bin/server.js\", \"--config=${XDG_CONFIG_HOME}/app/config.json\"],\n      \"env\": {\n        \"API_KEY\": \"${MY_API_KEY}\",\n        \"LOG_DIR\": \"${HOME}/logs\"\n      }\n    },\n    \"api-server\": {\n      \"description\": \"HTTP server with authentication\",\n      \"type\": \"http\",\n      \"url\": \"https://api.example.com\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${API_TOKEN}\"\n      }\n    }\n  }\n}\n```\n\n**Important notes**:\n- Environment variables must be set before starting Modular MCP\n- If a referenced environment variable is not defined, a warning will be logged and the original placeholder (e.g., `${UNDEFINED_VAR}`) will be preserved\n- Variables are substituted at load time, so the config file remains safe to commit\n\n### 2. Register Modular MCP\n\nRegister Modular MCP in your MCP client configuration (e.g., `.mcp.json` for Claude Code):\n\n```json\n{\n  \"mcpServers\": {\n    \"modular-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@kimuson/modular-mcp\", \"modular-mcp.json\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n### 3. Two Tools Registration\n\nWhen Modular MCP starts, it registers only two tools to the LLM:\n\n- `get-modular-tools`: Retrieves tool name and schemas for a specific group\n- `call-modular-tool`: Executes a tool from a specific group\n\nThe `get-modular-tools` tool description includes information about available groups, like this:\n\n```\nmodular-mcp manages multiple MCP servers as organized groups, providing only the necessary group's tool descriptions to the LLM on demand instead of overwhelming it with all tool descriptions at once.\n\nUse this tool to retrieve available tools in a specific group, then use call-modular-tool to execute them.\n\nAvailable groups:\n- context7: Use when you need to search library documentation.\n- playwright: Use when you need to control or automate web browsers.\n```\n\nThis description is passed to the LLM as part of the system prompt, allowing it to discover available groups without making any tool calls.\n\n### 4. On-Demand Tool Loading\n\nThe LLM can now load and use tools on a per-group basis:\n\n1. **Discovery**: The LLM sees available groups in the tool description (no tool calls needed)\n2. **Exploration**: When the LLM needs playwright tools, it calls `get-modular-tools` with `group=\"playwright\"`\n3. **Execution**: The LLM uses `call-modular-tool` to execute specific tools like `browser_navigate`\n\nFor example, to automate a web browser:\n```\nget-modular-tools(group=\"playwright\")\n→ Returns all playwright tool schemas\n\ncall-modular-tool(group=\"playwright\", name=\"browser_navigate\", args={\"url\": \"https://example.com\"})\n→ Executes the navigation through the playwright MCP server\n```\n\nThis workflow keeps context usage minimal while providing access to all tools when needed.\n\n## Benefits\n\n- **Reduced Context Usage**: Only loads tool information when actually needed\n- **Scalable**: Can manage dozens of MCP servers without overwhelming context\n- **Flexible**: Easy to add/remove tool groups without affecting others\n- **Transparent**: Tools execute exactly as if called directly on upstream servers\n\n## Migration from Standard MCP Configuration\n\nIf you already have a standard MCP configuration file (e.g., `.mcp.json`), you can easily migrate it to Modular MCP format using the built-in migration command.\n\n### Using the Migration Command\n\nRun the migration command with your existing MCP configuration file:\n\n```bash\nnpx -y @kimuson/modular-mcp migrate \u003cmcp-config-file-path\u003e\n```\n\nFor example, if you have a `.mcp.json` file:\n\n```bash\nnpx -y @kimuson/modular-mcp migrate .mcp.json\n```\n\nThe migration command will:\n1. Generate a `modular-mcp.json` file with the migrated configuration (defaults to `modular-mcp.json` in the current directory, or use `-o` to specify a custom path)\n2. Replace the original file's contents with a Modular MCP server configuration that references the generated `modular-mcp.json` file\n\n## OAuth Authentication for Remote MCP Servers\n\nModular MCP supports OAuth-based authentication for remote MCP servers using both `sse` and `http` transports.\n\n### Using Built-in OAuth Support (Experimental)\n\nModular MCP includes an experimental OAuth client that implements the [MCP Authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization):\n\n```json\n{\n  \"mcpServers\": {\n    \"linear-server\": {\n      \"description\": \"Use when you want to check Linear tickets, etc.\",\n      \"type\": \"sse\",\n      \"url\": \"https://mcp.linear.app/sse\"\n    }\n  }\n}\n```\n\nOn first connection, your browser will open for OAuth authentication. Tokens are stored locally in `~/.modular-mcp/oauth-servers/` and reused automatically.\n\n**Note:** This feature is experimental. If you encounter issues, use the fallback method below.\n\n### Fallback: Using mcp-remote via stdio\n\nFor compatibility with all OAuth servers, you can use `mcp-remote` via `stdio` transport:\n\n```json\n{\n  \"mcpServers\": {\n    \"linear-server\": {\n      \"description\": \"Use when you want to check Linear tickets, etc.\",\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"https://mcp.linear.app/sse\"]\n    }\n  }\n}\n```\n\nThis approach delegates OAuth handling to the `mcp-remote` client and is recommended if the experimental OAuth support doesn't work for your server.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-kimuson%2Fmodular-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fd-kimuson%2Fmodular-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fd-kimuson%2Fmodular-mcp/lists"}