mcp-data-server

Proyecto de ejemplo que demuestra patrones de producción para web-scraping / automatización.

Un servidor MCP que le da a Claude (o a cualquier cliente MCP) acceso de solo lectura a una base de datos empresarial — con las salvaguardas que hacen que conectar un LLM a datos reales de la empresa sea aceptable: conexión de solo lectura, lista blanca de tablas, enmascaramiento de PII, límite de filas, tiempo de espera de consulta y un registro de auditoría completo.

Pregunta "¿qué países piden más y cuánto nos costaron los reembolsos el último trimestre?" en Claude Desktop y obtén la respuesta desde la base de datos real — sin que el modelo pueda escribir, eliminar, adjuntar o leer una tabla que no se le haya concedido.

Por qué existe esto

El obstáculo en la mayoría de los proyectos "conectar IA a nuestros datos" no es la conexión, sino la primera pregunta de quien sea dueño de la base de datos: ¿qué impide que lea o rompa algo que no debería? Este servidor responde esa pregunta en código.

Related MCP server: Database Assistant MCP Server

Cuatro barreras independientes

Cada sentencia ejecutada se añade al registro de auditoría con su recuento de filas y duración, para que el propietario de los datos pueda ver exactamente lo que el modelo solicitó.

2026-08-18T11:22:41  6 rows in 1ms       SELECT country, COUNT(*) FROM customers GROUP BY 1 LIMIT 201
2026-08-18T11:22:44  error: rejected     DELETE FROM customers

Herramientas expuestas

Además de un recurso schema://tables, para que un cliente pueda cargar todo el esquema sin gastar una llamada de herramienta.

Inicio rápido

git clone https://github.com/dkautomation23/mcp-data-server.git
cd mcp-data-server
python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -r requirements.txt

python -m mcp_data_server.seed                    # creates demo.db
cp .env.example .env                              # then point DATABASE_PATH at your file
python -m mcp_data_server                         # serves over stdio

Python 3.10+. La base de datos de demostración tiene customers, orders, order_items y una tabla deliberadamente sensible internal_notes utilizada a continuación para mostrar el bloqueo de la lista blanca.

Conéctalo a Claude Desktop

Añadir a claude_desktop_config.json (ejemplo completo en examples/claude_desktop_config.json):

{
  "mcpServers": {
    "business-data": {
      "command": "python",
      "args": ["-m", "mcp_data_server"],
      "cwd": "C:/path/to/mcp-data-server",
      "env": {
        "DATABASE_PATH": "C:/path/to/your.db",
        "ALLOWED_TABLES": "customers,orders,order_items",
        "MASKED_COLUMNS": "customers.email,customers.phone"
      }
    }
  }
}

Conéctalo a Claude Code

claude mcp add business-data -- python -m mcp_data_server

Cómo es una sesión

Salida real del servidor en ejecución (consulta examples/demo_session.md para la transcripción completa):

// run_sql("SELECT status, COUNT(*) n, ROUND(SUM(total_eur)) revenue FROM orders GROUP BY 1 ORDER BY 3 DESC")
{
  "sql": "SELECT status, COUNT(*) n, ROUND(SUM(total_eur)) revenue FROM orders GROUP BY 1 ORDER BY 3 DESC LIMIT 201",
  "columns": ["status", "n", "revenue"],
  "rows": [["paid", 92, 149914.0], ["pending", 39, 64596.0], ["refunded", 31, 45911.0]],
  "row_count": 3, "truncated": false, "elapsed_ms": 0
}

// run_sql("DELETE FROM customers")
{ "error": "only SELECT (or WITH ... SELECT) statements are allowed" }

// run_sql("SELECT * FROM internal_notes")
{ "error": "table 'internal_notes' is not in the allowlist (allowed: customers, orders, order_items)" }

// run_sql("SELECT id, name, email FROM customers LIMIT 2")
{ "rows": [[1, "Customer 001", "***"], [2, "Customer 002", "***"]] }

Configuración

Pruebas

pytest -q

...............................                                          [100%]
31 passed in 1.77s

Tres capas: las salvaguardas SQL (inyección, segundas sentencias, contrabando de comentarios, tablas prohibidas), la capa de base de datos contra un archivo real sembrado (incluyendo un intento de escritura que el propio SQLite rechaza), y siete pruebas que impulsan el servidor sobre el protocolo MCP real — el mismo flujo de handshake, list_tools y call_tool que realiza un cliente de escritorio.

Adaptarlo a la pila de un cliente

• Postgres / MySQL: reemplaza la conexión en db.py con un controlador agrupado y una sesión SET TRANSACTION READ ONLY; la capa de validación no cambia.

• Herramientas específicas del negocio: añade una función con @mcp.tool() en server.py — un top_customers(period) bien nombrado supera a hacer que el modelo escriba SQL.

• Transporte HTTP en lugar de stdio: mcp.run(transport="streamable-http"), luego ponlo detrás de tu propia autenticación.

Licencia

MIT — consulta LICENSE.