# SuperMCP
SuperMCP is an orchestration layer for Model Context Protocol (MCP) servers. It gives an AI assistant a single entry point to dynamically discover, inspect, and call tools across many MCP servers — without hard-coding anything.
## How It Works
```
SuperMCP starts
└─ reads SUPERMCP_REGISTRY (env var, or from .env file)
└─ points to a registry file anywhere on disk
└─ loads mcpServers from that file
└─ resolves relative paths from the registry's directory
```
Because the registry file can live **anywhere**, you can keep your servers and their configuration wherever makes sense — a project folder, a shared drive, a dotfiles repo — and just point SuperMCP at it.
## Quick Start
1. **Clone & install dependencies**
```bash
git clone https://github.com/YakupAtahanov/SuperMCP.git
cd SuperMCP
uv pip install "mcp[cli]"
```
2. **Configure the registry path**
```bash
cp .env.example .env
```
Edit `.env`:
```
SUPERMCP_REGISTRY=C:/Users/you/my-servers/mcp.json
```
The path can be absolute or relative (relative paths resolve from the SuperMCP directory).
Alternatively, pass it as an environment variable when launching:
```bash
SUPERMCP_REGISTRY=/path/to/mcp.json python SuperMCP.py
```
Or set it in your MCP host (e.g. Cursor):
```json
{
"command": "python",
"args": ["C:/path/to/SuperMCP.py"],
"env": { "SUPERMCP_REGISTRY": "C:/Users/you/my-servers/mcp.json" }
}
```
3. **Create your registry file** at that location:
```json
{
"mcpServers": {
"ShellMCP": {
"command": "python",
"args": [".mcps/ShellMCP/server.py"],
"type": "stdio",
"description": "Shell command execution",
"enabled": true
}
}
}
```
Relative paths inside the registry (like `.mcps/ShellMCP/server.py`) resolve from the registry file's directory.
4. **Run**
```bash
python SuperMCP.py
```
## Available Tools
| Tool | Description |
|------|-------------|
| `reload_servers` | Reload the registry and rebuild the in-memory server list |
| `list_servers` | List all registered MCP servers |
| `inspect_server` | Inspect a server's tools, prompts, and resources |
| `call_server_tool` | Call a tool on any registered server |
| `add_server` | Add a new server (SSE or stdio) to the registry |
| `remove_server` | Remove a server from the registry |
| `update_server` | Update a server's configuration |
## Server Types
### Stdio (local process)
```json
{
"mcpServers": {
"my-server": {
"command": "python",
"args": ["path/to/server.py"],
"type": "stdio",
"description": "A local MCP server",
"enabled": true
}
}
}
```
### SSE (remote endpoint)
```json
{
"mcpServers": {
"remote-server": {
"url": "https://example.com/mcp/sse",
"type": "sse",
"description": "A remote SSE server",
"enabled": true,
"env": {
"API_KEY": "your-key"
}
}
}
}
```
Environment variables in the `env` field are sent as HTTP headers in the format `X-MCP-{VAR_NAME}`.
### Git-based Stdio
```json
{
"mcpServers": {
"weather-mcp": {
"command": "python",
"args": [".mcps/remote/weather-mcp/server.py"],
"type": "stdio",
"url": "https://github.com/user/weather-mcp.git",
"description": "Cloned from Git, runs locally",
"enabled": true
}
}
}
```
When a stdio server has a `url` field, SuperMCP clones the repository into `.mcps/remote/<name>/` (relative to the registry) and installs its dependencies.
## Project Structure
```
SuperMCP/
├── SuperMCP.py # Main orchestration server
├── server_manager.py # Git cloning, SSE testing, dependency install
├── .env.example # Template — copy to .env and set SUPERMCP_REGISTRY
├── pyproject.toml # Python dependencies
├── ARCHITECTURE.md # Architecture overview
└── README.md
```
## Contributing
Contributions welcome. Whether you're building new MCP servers, improving the orchestration layer, or enhancing documentation — all help is appreciated.
## License
See [LICENSE](LICENSE).
