๐ FluidMCP CLI
Orchestrate multiple MCP servers with a single configuration file
---
## โก Quick Start - Run Multiple MCP Servers
The main power of FluidMCP is running multiple MCP servers from a single configuration file over a unified FastAPI endpoint.
### 1. Create a Configuration File
Create a `config.json` file with your MCP servers:
```json
{
"mcpServers": {
"google-maps": {
"command": "npx",
"args": ["-y", "@google-maps/mcp-server"],
"env": {
"GOOGLE_MAPS_API_KEY": "your-api-key"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
"env": {}
}
}
}
```
### 2. Launch All Servers
```bash
fluidmcp run config.json --file --start-server
```
This will:
- Install and configure all MCP servers listed in your config
- Launch them through a unified FastAPI gateway
- Make them available at `http://localhost:8099`
- Provide automatic API documentation at `http://localhost:8099/docs`
---
## ๐ Features
- **๐ Multi-Server Orchestration**
- Define multiple MCP servers in a single JSON configuration file
- Launch all servers with one command: `fluidmcp run --file `
- Unified FastAPI gateway serving all your MCP tools
- **๐ฆ Package Management**
- Install MCP packages with `fluidmcp install author/package@version`
- Automatic dependency resolution and environment setup
- Support for npm, Python, and custom MCP servers
- **๐ FastAPI Gateway**
- Unified HTTP endpoints for all MCP tools
- Server-Sent Events (SSE) streaming support
- Swagger documentation at `/docs`
- **๐ Security & Authentication**
- Bearer token authentication
- Secure mode with encrypted communications
- Environment variable encryption for API keys
---
## ๐ฅ Installation
```bash
pip install fluidmcp
```
---
## ๐ง Alternative Usage Patterns
### Install Individual Packages
```bash
fluidmcp install author/package@version
```
### List Installed Packages
```bash
fluidmcp list
```
### Run Individual Package
```bash
fluidmcp run author/package@version --start-server
```
---
## ๐ Advanced Usage
### Secure Mode with Authentication
Run with bearer token authentication:
```bash
fluidmcp run config.json --file --secure --token your_token --start-server
```
---
### after authorisation
---
### โ๏ธ Run from S3 URL
Run configuration directly from S3:
```bash
fluidmcp run "https://bucket.s3.amazonaws.com/config.json" --s3
```
**Common Options:**
- `--start-server` โ Starts FastAPI server
- `--master` โ Use S3-driven config
- `--file` โ Run from local config.json
- `--s3` โ Run from S3 URL
- `--secure` โ Enable secure token mode
- `--token ` โ Custom bearer token
- `--verbose` โ Enable verbose logging (DEBUG level)
### Run All Installed Packages
```bash
fluidmcp run all --start-server
```
---
## ๐ Run Modes
### ๐ง Master Mode (S3 Centralized)
```bash
fluidmcp install author/package@version --master
fluidmcp run all --master
```
---
## ๐งฉ Environment Variables
```bash
# S3 Credentials (used in --master mode)
export S3_BUCKET_NAME="..."
export S3_ACCESS_KEY="..."
export S3_SECRET_KEY="..."
export S3_REGION="..."
# Registry access
export MCP_FETCH_URL="https://registry.fluidmcp.com/fetch-mcp-package"
export MCP_TOKEN="..."
```
### Edit Environment
```bash
fluidmcp edit-env
```
### Show Version
```bash
fluidmcp --version
```
Displays FluidMCP version, Python version, and installation path.
### Validate Configuration
```bash
# Validate a local configuration file
fluidmcp validate config.json --file
# Validate an installed package
fluidmcp validate author/package@version
```
The `validate` command checks:
- Configuration file structure and resolution
- Command availability in system PATH
- Required environment variables (marked with `required: true`)
- Optional environment variables and tokens
- Metadata.json existence for installed packages
**Note:** Environment variable lookup is case-insensitive. For example, if your config specifies `github_token`, the validator will check both `github_token` and `GITHUB_TOKEN` in your environment.
The command distinguishes between **errors** (fatal issues) and **warnings** (non-fatal issues):
**Errors (exit code 1):**
- Missing commands in PATH
- Missing required environment variables
- Configuration resolution failures
**Warnings (exit code 0):**
- Missing optional environment variables
- Missing TOKEN variables not explicitly marked as required
Example outputs:
**Success:**
```
โ Configuration is valid with no issues found.
```
**With warnings only:**
```
โ ๏ธ Configuration is valid with warnings:
- Optional env var 'DEBUG_MODE' is not set (server: test-server)
- Token env var 'GITHUB_TOKEN' is not set (server: github-server)
โ No fatal errors found. You may proceed, but consider addressing the warnings above.
```
**With errors:**
```
โ Configuration validation failed with errors:
- Command 'nonexistent-command' not found in PATH (server: test-server)
- Missing required env var 'API_KEY' (server: test-server)
โ ๏ธ Warnings:
- Optional env var 'DEBUG_MODE' is not set (server: test-server)
```
---
## ๐ Directory Layout
```
.fmcp-packages/
โโโ Author/
โโโ Package/
โโโ Version/
โโโ metadata.json
โโโ [tool files]
```
---
## ๐ metadata.json Example
```json
{
"mcpServers": {
"maps": {
"command": "npx",
"args": ["-y", "@package/server"],
"env": {
"API_KEY": "xxx"
}
}
}
}
```
---
## ๐งช Try an MCP Server
```bash
fluidmcp install Google_Maps/google-maps@0.6.2
fluidmcp run all
```
Then call it using:
```python
import requests, json
url = "http://localhost:8099/google-maps/mcp"
payload = {
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "maps_search_places",
"arguments": {
"query": "coffee shops in San Francisco"
}
}
}
response = requests.post(url, json=payload)
print(json.dumps(response.json(), indent=2))
```
---
## ๐ก Streaming with SSE
```bash
curl -N -X POST http://localhost:8099/package/sse \
-H "Content-Type: application/json" \
-d @payload.json
```
- `sse/start`
- `sse/stream`
- `sse/message`
- `sse/tools_call`
Useful for LLMs, web scraping, or AI workflows that stream data.
---
## ๐ธ Demo
### Installing an individual package
---
### Running an individual package
---
### Edit environment of a package
---
## ๐ค Contribute
FluidMCP is open for collaboration. We welcome contributions from the community!
- **Contributing Guide**: See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines
- **Report Issues**: Open an issue on [GitHub](https://github.com/Fluid-AI/fluidmcp/issues)
- **Submit PRs**: Follow our contribution guidelines to submit pull requests
---
## ๐ License
[GNU General Public License v3.0](LICENSE)
---