fluidmcp

🌀 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:

{
  "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

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

pip install fluidmcp

🔧 Alternative Usage Patterns

Install Individual Packages

fluidmcp install author/package@version

List Installed Packages

fluidmcp list

Run Individual Package

fluidmcp run author/package@version --start-server

🔐 Advanced Usage

Secure Mode with Authentication

Run with bearer token authentication:

fluidmcp run config.json --file --secure --token your_token --start-server

after authorisation

☁️ Run from S3 URL

Run configuration directly from S3:

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

fluidmcp run all --start-server

📂 Run Modes

🧠 Master Mode (S3 Centralized)

fluidmcp install author/package@version --master
fluidmcp run all --master

🧩 Environment Variables

# 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

fluidmcp edit-env

Show Version

fluidmcp --version

Displays FluidMCP version, Python version, and installation path.

Validate Configuration

# 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

{
  "mcpServers": {
    "maps": {
      "command": "npx",
      "args": ["-y", "@package/server"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}

🧪 Try an MCP Server

fluidmcp install Google_Maps/google-maps@0.6.2
fluidmcp run all

Then call it using:

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

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 for development setup and guidelines
• Report Issues: Open an issue on GitHub
• Submit PRs: Follow our contribution guidelines to submit pull requests

📌 License

GNU General Public License v3.0