Multiverse MCP Server

1# Multiverse MCP Server
2 
3A middleware server that enables multiple isolated instances of the same MCP servers to coexist independently with unique namespaces and configurations.
4 
5The Multiverse MCP Server creates isolated operational spaces where identical MCP servers can run simultaneously without conflicts. Each "universe" maintains its own configuration, filesystem access, and function naming, enabling developers to run multiple instances of the same server type while maintaining complete separation between different contexts or projects.
6 
7## Key Features
8 
9### Run Multiple Instances
10Run multiple instances of the same MCP server type independently and simultaneously. Each instance operates in its own isolated universe with separate configurations. This enables scenarios like:
11- Multiple MySQL servers `mcp-server-mysql` pointing to different databases
12- Multiple Git servers `mcp-server-git` with different Personal Access Tokens
13- Multiple filesystem servers `mcp-server-filesystem` accessing different root paths
14 
15### Automatic Server Restart
16Register your MCP server with file watching capability during development. When enabled, the server automatically detects changes in the specified directory and performs a graceful restart, making development and testing seamless.
17 
18### JSON-based Configuration System
19Define your multiverse setup using a simple and flexible JSON configuration format. Each server instance can be configured with its own:
20- Command and arguments
21- Environment variables
22- Path resolution rules
23- File watching settings
24 
25## Installation
26 
27First, ensure you've downloaded and installed the [Claude Desktop app](https://claude.ai/download) and you have npm installed.
28 
29Next, add this entry to your `claude_desktop_config.json` 
30- on Mac, found at `~/Library/Application\ Support/Claude/claude_desktop_config.json`
31- on Windows, found at `C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json`
32 
33Now add how many multiverse servers you want to run. For example, if you want to run two instances of `mcp-server-multiverse`, one for your job and one for your side project, you can add the following configuration:
34 
35```json
36{
37  "mcpServers": {
38    "job-multiverse": {
39      "command": "npx",
40      "args": [
41        "-y",
42        "@lamemind/mcp-server-multiverse@latest",
43        "/path/to/your/job-multiverse.json"
44      ]
45    },
46    "side-project-multiverse": {
47      "command": "npx",
48      "args": [
49        "-y",
50        "@lamemind/mcp-server-multiverse@latest",
51        "/path/to/your/side-project-multiverse.json"
52      ]
53    }
54  }
55}
56```
57 
58This config allows Claude Desktop to automatically start the `mcp-server-multiverse` instances when you start the app.
59 
60![demo.png](assets/demo.png)
61 
62## Configuration Examples
63 
64### Create two isolated instances of `mcp-server-mysql` with different databases
65 
66Your `job-multiverse.json` file
67~~~JSON
68{
69  "serverName": "JobMultiverse",
70  "functionsPrefix": "job",
71  "servers": [
72    {
73      "command": "npx",
74      "args": [
75        "-y",
76        "@benborla29/mcp-server-mysql"
77      ],
78      "env": {
79        "MYSQL_HOST": "127.0.0.1",
80        "MYSQL_PORT": "3306",
81        "MYSQL_USER": "root",
82        "MYSQL_PASS": "",
83        "MYSQL_DB": "my-job-db"
84      }
85    }
86  ]
87}
88~~~
89 
90Your `side-project-multiverse.json` file
91~~~JSON
92{
93  "serverName": "SideProjectMultiverse",
94  "functionsPrefix": "side-project",
95  "servers": [
96    {
97      "command": "npx",
98      "args": [
99        "-y",
100        "@benborla29/mcp-server-mysql"
101      ],
102      "env": {
103        "MYSQL_HOST": "127.0.0.1",
104        "MYSQL_PORT": "3306",
105        "MYSQL_USER": "root",
106        "MYSQL_PASS": "",
107        "MYSQL_DB": "side-project-db"
108      }
109    }
110  ]
111}
112~~~
113 
114 
115### Create an isolated instance of `mcp-server-filesystem`
116 
117- The `mcp-server-filesystem`'s functions will be exposed with `side-project` prefix, e.g. `side-project_read_file`, `side-project_write_file`.
118- The root path can be hidden from the client (e.g. Claude Desktop) by using the `pathResolution` configuration.
119 
120Note that `pathResolution` is optional and is only needed if you want to hide the root path from the client.
121 
122Your `multiverse.json` file
123~~~JSON
124{
125  "serverName": "MySideProject",
126  "functionsPrefix": "side-project",
127  "servers": [
128    {
129      "command": "npx",
130      "args": [
131        "-y",
132        "@modelcontextprotocol/server-filesystem@latest",
133        "/full/path/to/side-project"
134      ],
135      "pathResolution": {
136        "root": "/full/path/to/side-project",
137        "applyTo": [
138          "path",
139          "paths"
140        ]
141      }
142    }
143  ]
144}
145~~~
146 
147 
148### Automatic server restart on file changes with `fileWatch`
149 
150Your `multiverse.json` file
151~~~JSON
152{
153  "serverName": "MySideProject",
154  "functionsPrefix": "side-project",
155  "servers": [
156    {
157      "command": "node",
158      "args": [
159        "/my-own/mcp-server/i-m-working-on/build/index.js"
160      ],
161      "fileWatch": {
162        "enabled": true,
163        "path": "/my-own/mcp-server/i-m-working-on/build/"
164      }
165    }
166  ]
167}
168~~~
169 
170### Hiding specific functions with the `hideFunctions` option
171 
172You can selectively hide specific functions from wrapped servers using the `hideFunctions` array. This is useful when you want to use a server but restrict access to certain potentially dangerous or unnecessary functions.
173 
174The `hideFunctions` array accepts a list of function names that should be hidden from the wrapped server. When a function is hidden:
175- It won't be registered with the main MCP server
176- It won't be available to the client (e.g., Claude Desktop)
177- It won't appear in the list of available functions
178 
179This feature is particularly useful for:
180- Restricting access to potentially dangerous functions (e.g., `delete_repository` in GitHub)
181- Simplifying the interface by hiding rarely used functions
182- Creating different permission levels for different server instances
183 
184~~~JSON
185{
186  "serverName": "GitHubWithRestrictions",
187  "functionsPrefix": "github",
188  "servers": [
189    {
190      "command": "npx",
191      "args": [
192        "-y",
193        "@modelcontextprotocol/server-github@latest"
194      ],
195      "env": {
196        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-personal-access-token>"
197      },
198      "hideFunctions": [
199        "create_repository",
200        "delete_repository",
201        "create_issue"
202      ]
203    }
204  ]
205}
206~~~
207 
208In this example, the GitHub server will start normally, but the functions `create_repository`, `delete_repository`, and `create_issue` will be hidden and unavailable to the client.
209 
210 
211### Disabling specific servers with the `enabled` flag
212 
213You can selectively disable specific servers in your configuration without removing them from the JSON file by setting the `enabled` flag to `false`. This is useful for temporarily disabling servers during development or testing.
214~~~JSON
215{
216  "serverName": "MySideProject",
217  "functionsPrefix": "side-project",
218  "servers": [
219    {
220      "command": "npx",
221      "args": [
222        "-y",
223        "@modelcontextprotocol/server-filesystem@latest",
224        "/full/path/to/side-project"
225      ],
226      "hideFunctions": [ "write_file" ]
227    },
228    {
229      "enabled": false,
230      "command": "npx",
231      "args": [
232        "-y",
233        "@modelcontextprotocol/server-github@latest"
234      ]
235    }
236  ]
237}
238~~~
239 
240In this example, the first server (filesystem) will start but the function `write_file` has been hidden, the second server (GitHub) is disabled and won't be started.
241 
242### Full example of a `multiverse.json` file
243 
244This example demonstrates how to create a multiverse server with multiple instances of different server types.
245 
246Note that `pathResolution` is optional and is only needed if you want to hide the root path from the client.
247 
248~~~JSON
249{
250  "serverName": "HugeProjectWithALotOfResources",
251  "functionsPrefix": "huge-project",
252  "servers": [
253    {
254      "command": "node",
255      "args": [
256        "/my-own/mcp-server/i-m-working-on/build/index.js"
257      ],
258      "fileWatch": {
259        "enabled": true,
260        "path": "/my-own/mcp-server/i-m-working-on/build/"
261      }
262    },
263    {
264      "command": "npx",
265      "args": [
266        "-y",
267        "@modelcontextprotocol/server-filesystem@latest",
268        "/full/path/to/huge-project"
269      ],
270      "pathResolution": {
271        "root": "/full/path/to/huge-project",
272        "applyTo": [
273          "path",
274          "paths"
275        ]
276      }
277    },
278    {
279      "command": "npx",
280      "args": [
281        "-y",
282        "@modelcontextprotocol/server-github@latest"
283      ],
284      "env": {
285        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-personal-access-token>"
286      }
287    },
288    {
289      "command": "uvx",
290      "args": [
291        "mcp-server-git",
292        "--repository",
293        "/full/path/to/huge-project"
294      ],
295      "pathResolution": {
296        "root": "/full/path/to/huge-project",
297        "applyTo": [
298          "repo_path"
299        ]
300      }
301    }
302  ]
303}
304~~~
305 
306## To Do
307 
308- [ ] Add support for `Prompts`
309- [ ] Add support for `Resources`
310- [ ] Add a GUI for managing multiverse servers
311 
312## Verified Platforms
313 
314- [x] Windows
315- [ ] macOS
316- [ ] Linux
317 
318## License
319 
320MIT
321