@kimuson/modular-mcp weekly downloads statistics

Modular MCP

<!-- DeepWiki badge generated by https://deepwiki.ryoppippi.com/ -->

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.

Concept

Traditional MCP setups can overwhelm LLM context when dealing with numerous tools from multiple servers. Modular MCP solves this by:

• Context Efficiency: Group information is embedded in tool descriptions, so LLMs can discover available groups without making any tool calls
• On-Demand Loading: Retrieves detailed tool schemas only when needed for specific groups
• Separation of Concerns: Maintains clear phases between tool discovery and execution
• Proxy Architecture: Acts as a single MCP endpoint that manages multiple upstream MCP servers

How it works?

1. Configuration

Create 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.

Here's an example using Context7 and Playwright MCP servers:

{
+ "$schema": "https://raw.githubusercontent.com/d-kimuson/modular-mcp/refs/heads/main/config-schema.json",
  "mcpServers": {
    "context7": {
+     "description": "Use when you need to search library documentation.",
-     "type": "stdio",
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"],
      "env": {}
    },
    "playwright": {
+     "description": "Use when you need to control or automate web browsers.",
-     "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "env": {}
    }
  }
}

The 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.

Note: The type field defaults to "stdio" if not specified. For stdio type servers, you can omit the type field for cleaner configuration.

Environment Variable Interpolation

Modular MCP supports environment variable interpolation in configuration files, allowing you to avoid committing sensitive information like API keys and tokens to version control.

Supported syntax:

• ${VAR} - Braced variable reference

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

Where interpolation is supported:

• stdio servers: args array elements and env object values
• http/sse servers: url string and headers object values

Example:

{
  "mcpServers": {
    "my-server": {
      "description": "Example server with environment variables",
      "command": "node",
      "args": ["${HOME}/.local/bin/server.js", "--config=${XDG_CONFIG_HOME}/app/config.json"],
      "env": {
        "API_KEY": "${MY_API_KEY}",
        "LOG_DIR": "${HOME}/logs"
      }
    },
    "api-server": {
      "description": "HTTP server with authentication",
      "type": "http",
      "url": "https://api.example.com",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

Important notes:

• Environment variables must be set before starting Modular MCP
• If a referenced environment variable is not defined, a warning will be logged and the original placeholder (e.g., ${UNDEFINED_VAR}) will be preserved
• Variables are substituted at load time, so the config file remains safe to commit

2. Register Modular MCP

Register Modular MCP in your MCP client configuration (e.g., .mcp.json for Claude Code):

{
  "mcpServers": {
    "modular-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@kimuson/modular-mcp", "modular-mcp.json"],
      "env": {}
    }
  }
}

3. Two Tools Registration

When Modular MCP starts, it registers only two tools to the LLM:…