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

---