Universal MCP server
Commit Nov 4, 2026A modular Python-based ecosystem that provides AI clients with tools for data analysis, file management, system information, and automation.
Also known as rtostudioco/universal-mcp
- Stars
- 0
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 4, 2026
- License
- MIT
What is Universal MCP?
Universal is a modular Python-based ecosystem that provides AI clients with tools for data analysis, file management, system information, and automation. It exposes 5 tools, such as system, files, data.
Summary generated from the project's README
About Universal MCP server
Providing AI clients with a modular toolkit for data analysis, file management, and system automation is what universal-mcp achieves. This Python-based ecosystem allows developers to extend functionality through an auto-discovery mechanism where new modules are installed without modifying the core server. It supports multiple connection methods, including stdio for local use with Claude Desktop or IDEs, and streamable-http or SSE for remote access.
The server includes 31 tools organized into six specialized modules covering system information, file operations within a workspace sandbox, data processing for CSV and JSON, mathematical analysis, local NLP tasks, and automation utilities. Security is a central focus, featuring read-only SQLite access, AST-based math evaluation, and anti-SSRF protections for HTTP requests. Users can manage permissions using environment variables to allow or block specific tools and must explicitly enable shell execution via configuration.
Written from the project's README. Every use case is checked against a quote from it.
Universal MCP tools 5
Detected from the READMEsystemfilesdataanalysisautomation
Configuration
MCP_LOG_LEVELMCP_PLUGIN_DIRSMCP_TRANSPORTMCP_WORKSPACE_DIR
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablertostudioco/universal-mcp is public and reachablegithub.com/rtostudioco/universal-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/rtostudioco/universal-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubUniversal MCP 🧩
Ecosistema modular de herramientas de IA, datos, automatización y análisis sobre el Model Context Protocol.
Universal MCP es un servidor MCP en Python cuyo núcleo (MCP Core) es plenamente modular: los módulos se descubren e instalan automáticamente, así que puedes añadir herramientas nuevas sin reescribir el servidor. Soporta ambos transportes — stdio (para Claude Desktop / CLI) y streamable-http / sse (para acceso remoto).
✨ Características
- 🔌 Dos transportes:
stdio,streamable-httpysseseleccionables por configuración. - 🧩 Núcleo modular con auto-descubrimiento: builtin + plugins externos (
MCP_PLUGIN_DIRS) sin tocar el servidor. - 🛡️ Seguridad por diseño: sandbox de archivos, SQLite solo-lectura, evaluación matemática por AST-whitelist, bloqueo anti-SSRF, ejecución de shell desactivada por defecto, secretos enmascarados.
- 📦 31 tools listas para usar en 6 módulos.
- ⚙️ Configuración 100% por variables de entorno (
MCP_*/.env). - 🧪 Suite de pruebas completa (pytest + pytest-asyncio).
- 📚 Documentación de arquitectura y guía de extensión.
🚀 Instalación
Requiere Python ≥ 3.10.
cd universal-mcp
# Opción A — uv (rápido)
uv venv .venv
uv pip install -e ".[dev]" --python .venv/bin/python
# Opción B — pip clásico
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
🖥️ Uso
Transporte stdio (Claude Desktop, CLI, IDEs)
.venv/bin/python -m universal_mcp
# o, tras instalar:
universal-mcp
Configuración de ejemplo para Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"universal": {
"command": "/ruta/a/universal-mcp/.venv/bin/python",
"args": ["-m", "universal_mcp"],
"env": {
"MCP_LOG_LEVEL": "INFO",
"MCP_WORKSPACE_DIR": "/ruta/a/universal-mcp/workspace"
}
}
}
}
Transporte streamable-http (remoto / múltiples clientes)
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 universal-mcp
# Endpoint: http://127.0.0.1:8000/mcp
Transporte SSE (legado)
MCP_TRANSPORT=sse universal-mcp
🧰 Módulos incluidos (31 tools)
| Módulo | Tools | Descripción |
|---|---|---|
system |
system_info, system_now, system_disk_usage, system_env_vars, system_run_command |
Info del host, hora por zona horaria, disco, variables de entorno (secretos enmascarados), shell opt-in. |
files |
files_list_files, files_read_file, files_write_file, files_delete_file, files_search_files |
Archivos dentro del sandbox del workspace: listar, leer, escribir, borrar y búsqueda tipo grep (literal o regex). |
data |
data_read_csv, data_read_json, data_flatten_json, data_sqlite_query, data_to_json |
CSV/JSON del sandbox, aplanado de JSON y SQLite solo-lectura. |
analysis |
analysis_stats, analysis_math_eval, analysis_linear_regression, analysis_correlation, analysis_frequency |
Estadística descriptiva, calculadora segura (AST), regresión lineal, correlación de Pearson y frecuencias. |
ai |
ai_text_stats, ai_summarize, ai_sentiment, ai_keywords, ai_extract, ai_slugify |
NLP local (sin APIs): métricas de texto, resumen extractivo, sentimiento ES/EN, keywords, extracción de entidades y slugs. |
automation |
automation_http_request, automation_send_webhook, automation_uuid4, automation_timestamp, automation_wait |
HTTP con protección anti-SSRF, webhooks y utilidades. |
⚙️ Configuración (variables de entorno)
| Variable | Por defecto | Descripción |
|---|---|---|
MCP_SERVER_NAME |
universal-mcp |
Nombre visible por el cliente. |
MCP_TRANSPORT |
stdio |
stdio | streamable-http | sse. |
MCP_HOST / MCP_PORT |
127.0.0.1 / 8000 |
Bind de los transportes HTTP. |
MCP_LOG_LEVEL |
INFO |
Nivel de log (siempre a stderr). |
MCP_DISABLED_MODULES |
(vacío) | Módulos a omitir, p. ej. system,ai. |
MCP_PLUGIN_DIRS |
(vacío) | Directorios de plugins externos (desactivados salvo configuración explícita). |
MCP_ALLOWED_TOOLS |
(vacío = todas) | Allowlist de tools (globs), p. ej. data_*,system_*. |
MCP_BLOCKED_TOOLS |
(vacío) | Denylist de tools (globs); siempre gana sobre el allowlist. |
MCP_WORKSPACE_DIR |
./workspace |
Sandbox para files_* y data_*. |
MCP_ENABLE_SHELL |
false |
Habilita system_run_command. ⚠️ |
MCP_HTTP_BLOCK_PRIVATE |
true |
Bloquea IPs privadas/loopback (anti-SSRF). |
MCP_HTTP_TIMEOUT |
15 |
Timeout HTTP en segundos. |
MCP_MAX_OUTPUT_CHARS |
20000 |
Truncado de cuerpos HTTP. |
Consulta .env.example para una plantilla completa.
➕ Añadir un módulo nuevo (sin reescribir el servidor)
Opción 1 — módulo builtin: crea src/universal_mcp/modules/<nombre>/module.py:
from universal_mcp.core.base import BaseModule
from universal_mcp.core.context import ModuleContext
from universal_mcp.core.utils import to_json
class WeatherModule(BaseModule):
name = "weather" # prefijo de las tools: weather_*
def register(self, ctx: ModuleContext) -> None:
@ctx.tool(name="current", description="Weather for a city (demo).")
def current(city: str) -> str:
return to_json({"city": city, "temp_c": 21})
Reinicia el servidor: el registry lo detecta y registra automáticamente como weather_current.
Opción 2 — plugin externo (cero cambios de código): guarda el mismo archivo en cualquier carpeta y arranca con:
MCP_PLUGIN_DIRS=/ruta/a/mis/plugins universal-mcp
Guía completa: docs/ADDING_MODULES.md · Ejemplo ejecutable: examples/plugins/hello_plugin.py.
🔒 Modelo de seguridad
- Sandbox de archivos:
resolve_in_workspace()valida cada ruta (incluye symlinks) contraMCP_WORKSPACE_DIR. - SQLite de solo lectura:
PRAGMA query_only+ whitelistSELECT/WITH/PRAGMA/EXPLAIN. - Math por AST-whitelist: sin
eval; operaciones y funciones permitidas explícitamente. - Anti-SSRF por hop: resolución DNS + bloqueo de IPs privadas/loopback/reservadas en
automation_*. Las redirecciones no se siguen ciegamente: cada hop (Locationabsoluta o relativa) se re-valida, evitando el bypass clásico302 → 169.254.169.254. - Permisos por herramienta:
MCP_BLOCKED_TOOLS/MCP_ALLOWED_TOOLS(globs sobre el nombre final). Una tool bloqueada no se registra (se reporta enRegistrationReport.blocked_tools) y las registradas llevan guard en runtime (SecurityViolationError). - Sin registro parcial: si un módulo falla a mitad de registro, sus tools/resources a medias se revierten (rollback) y los nombres quedan libres; el resto de módulos no se ve afectado.
- Ciclo de vida:
setup()al cargar yteardown()al apagar (en orden inverso, tolerante a fallos), conectado a SIGINT/SIGTERM/atexit. - Shell opt-in:
system_run_commandresponde con error salvoMCP_ENABLE_SHELL=true. - Secretos enmascarados:
system_env_varsoculta valores de claves sensibles. - Plugins externos desactivados por defecto: solo se cargan con
MCP_PLUGIN_DIRSexplícito; se ejecutan in-process (sin sandbox) — úsalos solo con código de confianza. - Logging a stderr: stdout queda reservado al protocolo (crítico en stdio).
🧪 Pruebas
.venv/bin/pytest -v # suite completa (~75 tests)
.venv/bin/ruff check . # lint (opcional)
Cobertura: núcleo (config, registry, contexto, sandbox), integración del servidor (tools/list real vía FastMCP), y cada módulo (lógica pura + ejecución vía protocolo).
🗺️ Roadmap
- Hot-reload de módulos (
registry.reload()). - Resources y prompts builtin por módulo.
- Aislamiento por subprocess para plugins no confiables.
- Métricas (Prometheus) y traza de ejecución por tool.
- Autenticación para transporte HTTP (bearer/OAuth).
- Pinning de IP por conexión (mitigación completa de DNS rebinding).
📖 Documentación
docs/ARCHITECTURE.md— decisiones de diseño, diagramas y flujo de registro.docs/ADDING_MODULES.md— guía paso a paso para extender.
📄 Licencia
MIT — consulta LICENSE.
Universal MCP questions
What tools does Universal MCP provide?
It exposes 5 tools, including system, files, data, analysis, automation.
What transport protocols does it support?
The server supports stdio for local use with Claude Desktop or CLI, as well as streamable-http and SSE for remote access.