Modular

Create a JSON file that lists your upstream MCP servers, grouped by logical purpose. Each server entry needs a description (shown to the LLM), and the command/args to launch it. Use ${VAR} syntax for environment variable interpolation.

{
  "$schema": "https://raw.githubusercontent.com/d-kimuson/modular-mcp/refs/heads/main/config-schema.json",
  "mcpServers": {
    "playwright": {
      "description": "Browser automation tools for web scraping and UI testing",
      "command": "npx",
      "args": ["@playwright/mcp"],
      "env": {},
      "type": "stdio"
    },
    "filesystem": {
      "description": "Read and write files on the local filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {},
      "type": "stdio"
    }
  }
}

Run the server pointing at your config file to verify it starts without errors. The server will initialize connections to all configured upstream servers.

npx -y @kimuson/modular-mcp ./modular-mcp.json

Open your MCP client config (e.g. claude_desktop_config.json) and add a single entry for modular-mcp, pointing to your config file. This replaces the individual upstream server entries.

{
  "mcpServers": {
    "modular": {
      "command": "npx",
      "args": ["-y", "@kimuson/modular-mcp", "/absolute/path/to/modular-mcp.json"]
    }
  }
}

Restart Claude Desktop or your chosen client. It will now see only two tools from modular-mcp: 'get-modular-tools' and 'call-modular-tool'. The LLM fetches group schemas on demand rather than loading everything upfront.

Prompt the AI to discover what groups are available. It will call get-modular-tools to retrieve schemas for the requested group and then use call-modular-tool to execute actions.