FluidMCP CLI

Una herramienta de línea de comandos para ejecutar servidores MCP desde un solo archivo, con soporte para resolución automática de dependencias, configuración del entorno e instalación de paquetes desde fuentes locales o S3.

GitHub
8
Prueba este MCPPatrocinado

Documentación

🌀 FluidMCP CLI

Orquesta múltiples servidores MCP con un único archivo de configuración

⚡ Inicio rápido: ejecuta múltiples servidores MCP

El principal poder de FluidMCP es ejecutar múltiples servidores MCP desde un único archivo de configuración a través de un endpoint FastAPI unificado.

1. Crea un archivo de configuración

Crea un archivo config.json con tus servidores MCP:

{
  "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. Lanza todos los servidores

fluidmcp run config.json --file --start-server

Esto hará lo siguiente:

  • Instalará y configurará todos los servidores MCP listados en tu configuración
  • Los lanzará a través de una puerta de enlace FastAPI unificada
  • Los pondrá a disposición en http://localhost:8099
  • Proporcionará documentación automática de API en http://localhost:8099/docs

fluidmcp_file_

🚀 Características

  • 📁 Orquestación de múltiples servidores

    • Define múltiples servidores MCP en un único archivo de configuración JSON
    • Lanza todos los servidores con un solo comando: fluidmcp run --file <config.json>
    • Puerta de enlace FastAPI unificada que sirve todas tus herramientas MCP

  • 📦 Gestión de paquetes

    • Instala paquetes MCP con fluidmcp install author/package@version
    • Resolución automática de dependencias y configuración del entorno
    • Soporte para servidores MCP de npm, Python y personalizados

  • 🚀 Puerta de enlace FastAPI

    • Endpoints HTTP unificados para todas las herramientas MCP
    • Soporte de transmisión Server-Sent Events (SSE)
    • Documentación Swagger en /docs

  • 🔐 Seguridad y autenticación

    • Autenticación con token Bearer
    • Modo seguro con comunicaciones cifradas
    • Cifrado de variables de entorno para claves API

📥 Instalación

pip install fluidmcp

🔧 Patrones de uso alternativos

Instalar paquetes individuales

fluidmcp install author/package@version

Listar paquetes instalados

fluidmcp list

Ejecutar un paquete individual

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

🔐 Uso avanzado

Modo seguro con autenticación

Ejecuta con autenticación de token Bearer:

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

fluidmcp_secure_1

Después de la autorización

fluidmcp_secure_2

☁️ Ejecutar desde URL de S3

Ejecuta la configuración directamente desde S3:

fluidmcp run "https://bucket.s3.amazonaws.com/config.json" --s3

Opciones comunes:

  • --start-server – Inicia el servidor FastAPI
  • --master – Usa configuración impulsada por S3
  • --file – Ejecuta desde config.json local
  • --s3 – Ejecuta desde URL de S3
  • --secure – Habilita el modo de token seguro
  • --token <token> – Token Bearer personalizado
  • --verbose – Habilita el registro verboso (nivel DEBUG)

Ejecutar todos los paquetes instalados

fluidmcp run all --start-server

📂 Modos de ejecución

🧠 Modo maestro (centralizado en S3)

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

🧩 Variables de entorno

# 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="..."

Editar entorno

fluidmcp edit-env <author/package@version>

Mostrar versión

fluidmcp --version

Muestra la versión de FluidMCP, la versión de Python y la ruta de instalación.

Validar configuración

# Validate a local configuration file
fluidmcp validate config.json --file

# Validate an installed package
fluidmcp validate author/package@version

El comando validate comprueba:

  • La estructura del archivo de configuración y su resolución
  • La disponibilidad de comandos en el PATH del sistema
  • Las variables de entorno requeridas (marcadas con required: true)
  • Las variables de entorno y tokens opcionales
  • La existencia de Metadata.json para paquetes instalados

Nota: La búsqueda de variables de entorno no distingue entre mayúsculas y minúsculas. Por ejemplo, si tu configuración especifica github_token, el validador comprobará tanto github_token como GITHUB_TOKEN en tu entorno.

El comando distingue entre errores (problemas fatales) y advertencias (problemas no fatales):

Errores (código de salida 1):

  • Comandos faltantes en el PATH
  • Variables de entorno requeridas faltantes
  • Fallos en la resolución de la configuración

Advertencias (código de salida 0):

  • Variables de entorno opcionales faltantes
  • Variables TOKEN faltantes no marcadas explícitamente como requeridas

Ejemplos de salida:

Éxito:

✔ Configuration is valid with no issues found.

Solo con advertencias:

⚠️  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.

Con errores:

❌ 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)

📁 Estructura de directorios

.fmcp-packages/
└── Author/
    └── Package/
        └── Version/
            ├── metadata.json
            └── [tool files]

📑 Ejemplo de metadata.json

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

🧪 Prueba un servidor MCP

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

Luego llámalo usando:

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))

📡 Transmisión con 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

Útil para LLMs, web scraping o flujos de trabajo de IA que transmiten datos.

📸 Demostración

Instalación de un paquete individual

fluidmcp_install

Ejecución de un paquete individual

fluidmcp_run_individual (2)

Editar el entorno de un paquete

fluidmcp_edit-env (2)

🤝 Contribuye

FluidMCP está abierto a la colaboración. ¡Agradecemos las contribuciones de la comunidad!

  • Guía de contribución: Consulta CONTRIBUTING.md para la configuración de desarrollo y las pautas
  • Reportar problemas: Abre un issue en GitHub
  • Enviar PRs: Sigue nuestras pautas de contribución para enviar pull requests

📌 Licencia

Licencia Pública General de GNU v3.0