Universal MCP is a modular Python MCP server exposing 31 tools for system, file, data, analysis, NLP, and automation tasks over stdio, streamable-http, or SSE.
Inspect the host: OS/Python/CPU info, timezone-aware time, disk usage, env vars with secrets masked, and optional shell commands when enabled.
Manage sandboxed files: list, read, write/append, delete, and grep-like search with literal or regex queries.
Work with data: read CSV/JSON, flatten JSON, serialize JSON, and run read-only SQLite queries.
Analyze numbers: descriptive statistics, safe AST-whitelisted math evaluation, linear regression, Pearson correlation, and frequency counts.
Run local NLP: text metrics, extractive summaries, Spanish/English sentiment, keyword extraction, regex entity extraction, and slug generation.
Automate HTTP/webhooks: anti-SSRF HTTP requests, webhook JSON posts, UUIDs/timestamps, and wait/sleep for polling.
Extend via built-in modules or external plugins discovered at startup, with environment-based config and tool allow/deny lists.
Provides read-only SQLite database querying through the data_sqlite_query tool, restricted to SELECT/WITH/PRAGMA/EXPLAIN queries with PRAGMA query_only enforced.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Universal MCP read sales.csv and summarize the revenue stats"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
🔌 Dos transportes: stdio, streamable-http y sse seleccionables 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.
Related MCP server: RelayForge MCP
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]".venv/bin/python -m universal_mcp
# o, tras instalar:
universal-mcpConfiguració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"
}
}
}
}MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 universal-mcp
# Endpoint: http://127.0.0.1:8000/mcpMCP_TRANSPORT=sse universal-mcpMódulo | Tools | Descripción |
|
| Info del host, hora por zona horaria, disco, variables de entorno (secretos enmascarados), shell opt-in. |
|
| Archivos dentro del sandbox del workspace: listar, leer, escribir, borrar y búsqueda tipo grep (literal o regex). |
|
| CSV/JSON del sandbox, aplanado de JSON y SQLite solo-lectura. |
|
| Estadística descriptiva, calculadora segura (AST), regresión lineal, correlación de Pearson y frecuencias. |
|
| NLP local (sin APIs): métricas de texto, resumen extractivo, sentimiento ES/EN, keywords, extracción de entidades y slugs. |
|
| HTTP con protección anti-SSRF, webhooks y utilidades. |
Variable | Por defecto | Descripción |
|
| Nombre visible por el cliente. |
|
|
|
|
| Bind de los transportes HTTP. |
|
| Nivel de log (siempre a stderr). |
| (vacío) | Módulos a omitir, p. ej. |
| (vacío) | Directorios de plugins externos (desactivados salvo configuración explícita). |
| (vacío = todas) | Allowlist de tools (globs), p. ej. |
| (vacío) | Denylist de tools (globs); siempre gana sobre el allowlist. |
|
| Sandbox para |
|
| Habilita |
|
| Bloquea IPs privadas/loopback (anti-SSRF). |
|
| Timeout HTTP en segundos. |
|
| Truncado de cuerpos HTTP. |
Consulta .env.example para una plantilla completa.
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-mcpGuía completa: docs/ADDING_MODULES.md · Ejemplo ejecutable: examples/plugins/hello_plugin.py.
Sandbox de archivos: resolve_in_workspace() valida cada ruta (incluye symlinks) contra MCP_WORKSPACE_DIR.
SQLite de solo lectura: PRAGMA query_only + whitelist SELECT/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 (Location absoluta o relativa) se re-valida, evitando el bypass clásico 302 → 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 en RegistrationReport.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 y teardown() al apagar (en orden inverso, tolerante a fallos), conectado a SIGINT/SIGTERM/atexit.
Shell opt-in: system_run_command responde con error salvo MCP_ENABLE_SHELL=true.
Secretos enmascarados: system_env_vars oculta valores de claves sensibles.
Plugins externos desactivados por defecto: solo se cargan con MCP_PLUGIN_DIRS explí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).
.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).
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).
docs/ARCHITECTURE.md — decisiones de diseño, diagramas y flujo de registro.
docs/ADDING_MODULES.md — guía paso a paso para extender.
MIT — consulta LICENSE.
Extract entities by regex: kind ∈ {emails, urls, phones, numbers}.
Inputs: text (required), kind. Returns: result
Top keywords by frequency (stopwords ES/EN removed).
Inputs: text (required), top. Returns: result
Lexicon-based sentiment for Spanish/English text. Returns score in [-1,1] and label.
Inputs: text (required). Returns: result
Convert text to a URL-friendly slug (ASCII, hyphen-separated).
Inputs: text (required). Returns: result
Extractive summary: picks the most relevant sentences (word-frequency scoring, ES/EN stopwords) keeping original order. Max 10 sentences.
Inputs: text (required), max_sentences. Returns: result
Text metrics: chars, words, unique words, sentences, paragraphs, reading time.
Inputs: text (required). Returns: result
Pearson correlation coefficient (r, r², direction, strength).
Inputs: x (required), y (required). Returns: result
Count occurrences of each item and return the most common ones.
Inputs: items (required), top. Returns: result
Fit y = slope·x + intercept by least squares. Returns slope, intercept, r, r_squared and the equation string.
Inputs: x (required), y (required). Returns: result
Safely evaluate an arithmetic expression: + - * / // % **, parentheses, sqrt/sin/cos/tan/log/exp/abs/floor/ceil/round/min/max and pi/e/tau. No code execution.
Inputs: expression (required). Returns: result
Descriptive statistics for a list of numbers: n, sum, mean, median, min/max, stdev, variance and percentiles (p25/p50/p75/p90).
Inputs: numbers (required). Returns: result
Perform an HTTP request (GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS). Private/internal hosts are blocked by default (anti-SSRF), including redirect targets: every hop is re-validated. Body is truncated.
Inputs: url (required), body, method, headers, +2 more. Returns: result
POST a JSON payload to a webhook URL (adds X-Webhook-Secret header if provided). Redirect targets are re-validated (anti-SSRF).
Inputs: url (required), payload (required), secret. Returns: result
Current time: unix epoch and ISO-8601 UTC.
Inputs: no named parameters. Returns: result
Generate a random UUID v4 string.
Inputs: no named parameters. Returns: result
Sleep for N seconds (0.01–60). Useful for polling and retries.
Inputs: seconds. Returns: result
Flatten nested JSON objects/arrays into a single-level dict with dotted keys. Pass data as a JSON value.
Inputs: data (required), separator. Returns: result
Read a CSV file from the sandbox. Returns columns, sample rows and totals.
Inputs: path (required), limit, delimiter. Returns: result
Read and parse a JSON file from the sandbox (max 10 MB).
Inputs: path (required). Returns: result
Run a READ-ONLY SQL query (SELECT/WITH) against a SQLite file in the sandbox. Writes and DDL are blocked.
Inputs: sql (required), path (required), limit. Returns: result
Serialize any JSON-serializable data into a pretty JSON string.
Inputs: data (required), indent. Returns: result
Delete a file (never a directory) from the sandbox.
Inputs: path (required). Returns: result
List files/folders in the sandboxed workspace (relative paths only).
Inputs: path. Returns: result
Read a UTF-8 text file from the sandbox (max_bytes caps the output).
Inputs: path (required), max_bytes. Returns: result
Grep-like text search across sandbox files. Supports literal or regex queries. Returns matching file paths with line numbers.
Inputs: query (required), path, regex, max_results, +1 more. Returns: result
Write/append UTF-8 text to a file in the sandbox. Creates parent folders.
Inputs: path (required), content (required), append. Returns: result
Disk usage statistics (total/used/free bytes and percent) for a path.
Inputs: path. Returns: result
List environment variables (optionally by prefix). Secret-looking values are masked.
Inputs: prefix. Returns: result
Get host system information: OS, python, CPUs, hostname, cwd.
Inputs: no named parameters. Returns: result
Current date/time in a given IANA timezone (e.g. 'America/Bogota', 'UTC').
Inputs: tz. Returns: result
Execute a shell command on the host. DISABLED unless the server was started with MCP_ENABLE_SHELL=true. Use with extreme caution.
Inputs: command (required), timeout. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 31 tools
Most tools have clearly distinct purposes, but a few overlaps exist: automation_timestamp and system_now both return current time; ai_keywords and analysis_frequency both surface frequent terms; automation_http_request and automation_send_webhook overlap for POST/webhook use. These are distinguishable from descriptions, but an agent could still misselect in edge cases.
The set uses a consistent snake_case, category-prefixed convention across all tools. Minor inconsistency exists in that some names use a verb after the prefix (files_read_file, data_flatten_json) while others use a noun (analysis_correlation, system_info, ai_sentiment), but the pattern remains readable and predictable.
At 31 tools, the surface is heavy for a single server and exceeds the typical 3–15 well-scoped range. The broad 'Universal MCP' purpose explains the breadth, but the count still increases selection burden and cognitive load for an agent.
The server covers a wide range of utility domains: files, data, system, analysis, automation, and AI text processing. There are minor gaps such as no file copy/move operation and no CSV/JSON write path, but most workflows can be composed from existing tools.
Pay-per-call tools for AI assistants: code, data, finance, spreadsheets, media, web, time.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
A registry of AI agent tools — MCP servers, APIs, CLIs, SDKs — kept current by automated ingestion.