MCP‑Stack

Una colección de servidores MCP basada en Docker Compose para flujos de trabajo con LLM, que incluye configuración centralizada y scripts de gestión.

GitHubPrueba este MCPPatrocinado

Documentación

🧠 MCP‑Stack – Laboratorio Completo de Servidores MCP para Flujos con LLM

Versión final 2025‑06‑27 • Licencia MIT • Mantenimiento Luiz Peixoto

Este repositorio consolida 10 servidores MCP listos para uso local con LLMs (Google Gemini CLI, Claude, Cursor, VS Code AI). Cada servicio se orquesta mediante Docker Compose, con variables de entorno centralizadas, scripts de gestión y documentación. Un archivo compose.all.yml orquesta todos en lote.

🌳 Estructura de Directorios

mcp-stack/
├── compose.all.yml                # Orquestra todos os MCPs
├── .env.example                   # Variáveis de ambiente centralizadas (copie para .env)
├── .gemini/settings.json          # Endpoints prontos para Google‑CLI
├── scripts/
│   ├── start_all.sh               # Sobe todos os containers
│   └── stop_all.sh                # Encerra todos
└── servers/
    ├── memory-mcp/      # Weaviate (vetores)
    ├── github-mcp/      # Integração GitHub
    ├── filesystem-mcp/  # Arquivos locais
    ├── supabase-mcp/    # Banco Supabase
    ├── obsidian-mcp/    # Notas Obsidian
    ├── zotero-mcp/      # Referências Zotero
    ├── docgen-mcp/      # Geração de docs
    ├── hugo-mcp/        # Sites Hugo
    ├── ollama-mcp/      # Modelos Ollama
    └── fabric-mcp/      # Coleta Fabric (Daniel Miessler)

Cada subcarpeta servers/<mcp-name>/ contiene:

Archivo	Función
`docker-compose.yml`	Definición del contenedor + volúmenes + puertos
`README.md`	Enlace upstream + instrucciones específicas

🚀 Servidores MCP (Detalles)

Los detalles de cada servidor, incluidos puertos, repositorios y herramientas, permanecen iguales. Las configuraciones de entorno ahora se gestionan de forma centralizada.

📑 Archivos Globales

`.env.example`

Este archivo centraliza todas las variables de entorno necesarias para los servicios MCP. Cópielo a .env y ajuste los valores según su necesidad.

# Centralized environment variables for MCP-Stack

# memory-mcp
WEAVIATE_DATA=./data

# github-mcp & docgen-mcp
GITHUB_PAT=

# filesystem-mcp
PROJECTS_ROOT=/home/$USER/Projetos

# supabase-mcp
SUPABASE_PAT=
SUPABASE_PROJECT_REF=

# obsidian-mcp
VAULT_PATH=/home/$USER/Documentos/Obsidian/Vault

# zotero-mcp
ZOTERO_API_KEY=
ZOTERO_USER_ID=

# hugo-mcp
HUGO_SITES_ROOT=/home/$USER/Sites

# ollama-mcp (no specific variables)

# fabric-mcp (no specific variables)

`compose.all.yml`

Este archivo orquesta todos los servicios MCP, utilizando extends para reutilizar las definiciones de cada docker-compose.yml individual. También garantiza que las variables de entorno se carguen desde el .env centralizado.

`scripts/start_all.sh`

#!/usr/bin/env bash
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
docker compose -f "$SCRIPT_DIR/../compose.all.yml" up -d

`scripts/stop_all.sh`

#!/usr/bin/env bash
set -e
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
docker compose -f "$SCRIPT_DIR/../compose.all.yml" down

`.gemini/settings.json`

{
  "mcpServers": {
    "memory":     { "url": "http://localhost:9100" },
    "github":     { "url": "http://localhost:9101" },
    "filesystem": { "url": "http://localhost:9102" },
    "supabase":   { "url": "http://localhost:9103" },
    "obsidian":   { "url": "http://localhost:9104" },
    "zotero":     { "url": "http://localhost:9107" },
    "docgen":     { "url": "http://localhost:9105" },
    "hugo":       { "url": "http://localhost:9106" },
    "ollama":     { "url": "http://localhost:9108" },
    "fabric":     { "url": "http://localhost:9109" }
  }
}

🔥 Ejemplo de Flujo Completo

graph TD
subgraph Local Models
  OLL(Ollama‑mcp) -->|run_model| LLM((Resposta))
end
F(Fabric‑mcp) -->|ingest+summarize| MEM(memory‑mcp)
MEM -- contexto --> LLM
LLM -->|write_file| FILE(filesystem‑mcp)
FILE --> DOC(docgen‑mcp)
DOC --> G(GitHub‑mcp)
G --> H(Hugo‑mcp)

✅ Cómo Usar

Clone el repositorio y navegue hasta el directorio: git clone <repo> mcp-stack && cd mcp-stack
Cree su archivo de variables de entorno a partir del ejemplo: cp .env.example .env
Ajuste las variables en .env según sus necesidades (p. ej., GITHUB_PAT, VAULT_PATH).
Inicie todos los servicios MCP: ./scripts/start_all.sh
Configure el Gemini CLI para usar los endpoints de los MCPs: gemini settings import .gemini/settings.json

Pregunte a su agente (ejemplo):

"Use filesystem‑mcp para abrir README.md deste projeto e docgen‑mcp para gerar documentação HTML."

➕ Añadiendo Nuevos Servidores MCP

Para añadir un nuevo servidor MCP al stack:

Cree una nueva carpeta en servers/ (p. ej., servers/new-mcp/).
Dentro de ella, cree un docker-compose.yml para el nuevo servicio.
Añada las variables de entorno necesarias al .env.example centralizado.
Actualice compose.all.yml para incluir el nuevo servicio usando extends.
Añada el endpoint del nuevo servicio en .gemini/settings.json.

🛡️ Seguridad

Los tokens nunca van al Git.
filesystem-mcp monta solo la carpeta del proyecto – evite exponer ~/ completo.
En producción, coloque un proxy TLS (nginx/caddy) con autenticación básica.

📅 Roadmap Futuro

Mejoras Actuales: Implementación de health checks y fijación de versiones de imágenes Docker para mayor robustez y reproducibilidad.
2025‑Q3 — integración con PostgreSQL‑mcp y Redis‑mcp
2025‑Q4 — plantilla Ansible para despliegue remoto
2026‑Q1 — UI web para gestionar contenedores + health‑checks

🧪 Pruebas

Para verificar la accesibilidad y el funcionamiento básico de los servidores MCP, puede ejecutar las pruebas de reachability:

Instale las dependencias de prueba:
```
pip install -r requirements.txt
```
Asegúrese de que los servidores MCP estén en ejecución (./scripts/start_all.sh).
Ejecute el script de prueba:
```
python tests/test_mcp_servers.py
```