FluidMCP CLI MCP Server

A command-line tool to run MCP servers from a single file, with support for automatic dependency resolution, environment setup, and package installation from local or S3 sources.

GitHub
8

Dokumentasi

🌀 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

fluidmcp_file_

🚀 Features

  • 📁 Multi-Server Orchestration

    • Define multiple MCP servers in a single JSON configuration file
    • Launch all servers with one command: fluidmcp run --file <config.json>
    • 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

fluidmcp_secure_1

after authorisation

fluidmcp_secure_2

☁️ 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 <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 <author/package@version>

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/[email protected]
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

fluidmcp_install

Running an individual package

fluidmcp_run_individual (2)

Edit environment of a package

fluidmcp_edit-env (2)

🤝 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