# MCP Database

Servidores MCP en Python para conectar asistentes de IA (Cursor, Claude, Gemini, etc.) a **MySQL**, **Oracle**, **SQL Server**, **Informix** y **PostgreSQL**.

Hay cinco servidores independientes en el mismo repo:

| Servidor | Módulo | Entrada MCP | Driver extra en la PC |
|----------|--------|-------------|------------------------|
| MySQL | `mcp_mysql` | `mysql` | No (pip alcanza) |
| Oracle | `mcp_oracle` | `oracle` | No (pip / thin mode) |
| PostgreSQL | `mcp_postgresql` | `postgresql` | No (pip / `psycopg`) |
| SQL Server | `mcp_sqlserver` | `sqlserver` | **Sí** — ODBC Driver 17/18 |
| Informix | `mcp_informix` | `informix` | **Sí** — Client SDK / ODBC IBM |

## Requisitos

- Python 3.11+
- Acceso a la(s) base(s) que vayas a usar
- **SQL Server e Informix:** además de `pip install -e .`, debes instalar el driver nativo en cada máquina (ver sección abajo)

## Drivers adicionales (obligatorio para SQL Server e Informix)

`pip install -e .` instala `pyodbc`, pero **no** instala el driver del sistema. Sin eso, la conexión falla.

### SQL Server — ODBC Driver

1. Descarga e instala **Microsoft ODBC Driver 18 for SQL Server** (x64):  
   https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server
2. Si el instalador lo pide, instala también el [Visual C++ Redistributable](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist).
3. Verifica en PowerShell:

```powershell
Get-OdbcDriver | Where-Object { $_.Name -like "*SQL Server*" }
```

4. En `.env` usa el nombre exacto del driver, por ejemplo:

```env
SQLSERVER_DRIVER=ODBC Driver 18 for SQL Server
```

### Informix — Client SDK / ODBC

1. Descarga el **IBM Informix Client SDK** (incluye el ODBC Driver). Requiere cuenta/licencia IBM o HCL:  
   - https://www.ibm.com/support/pages/download-informix-products  
   - https://www.ibm.com/support/fixcentral  
   - HCL/Actian ESD: https://esd.actian.com/
2. Instala el Client SDK para **Windows x64**.
3. Verifica en *Orígenes de datos ODBC (64 bits)* que aparezca algo como `IBM INFORMIX ODBC DRIVER`.
4. En `.env`:

```env
INFORMIX_DRIVER=IBM INFORMIX ODBC DRIVER
INFORMIX_SERVER=ol_informix1410
```

`INFORMIX_SERVER` es el nombre del servidor Informix (`INFORMIXSERVER`), no solo el host.

## Instalación del proyecto

```bash
git clone <url-del-repo>
cd MCP-DATABASE
python -m venv .venv
```

Activa el entorno virtual:

```bash
# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1

# Linux / macOS
source .venv/bin/activate
```

Instala el paquete (incluye los cinco servidores):

```bash
pip install -e .
```

Crea tu archivo de credenciales (no se sube a git):

```bash
# Windows
Copy-Item .env.example .env

# Linux / macOS
cp .env.example .env
```

Edita `.env` con las bases que uses (ver `.env.example`).

## Setup rápido (recomendado)

Este repo incluye scripts que crean el `.venv`, instalan el paquete y copian `.env.example` → `.env` si no existe:

**Linux / macOS:**
```bash
./setup_claude_code.sh
```

**Windows (PowerShell):**
```powershell
.\setup_claude_code.ps1
```

Si PowerShell bloquea el script por la execution policy, corre una vez (o pídeselo a tu admin):
```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

Ninguno de los dos scripts toca `.env` con tus credenciales ni registra el MCP automáticamente — al terminar, imprimen el comando `claude mcp add` exacto (con la ruta al Python del `.venv` ya resuelta) para que:

1. Edites `.env` a mano con las credenciales de las bases que vayas a usar.
2. Corras ese `claude mcp add` por cada motor que quieras registrar (ver sección [Claude Code (CLI)](#claude-code-cli) abajo).

## Configurar el cliente MCP

Cada servidor se registra por separado (fusiona sin borrar otros MCPs):

```bash
python -m mcp_mysql setup
python -m mcp_oracle setup
python -m mcp_postgresql setup
python -m mcp_sqlserver setup
python -m mcp_informix setup
```

Opciones comunes:

```bash
python -m mcp_postgresql setup --client claude
python -m mcp_postgresql setup --dry-run
python -m mcp_postgresql setup --print
```

También: `mcp-mysql-setup` / `mcp-oracle-setup` / `mcp-postgresql-setup` / `mcp-sqlserver-setup` / `mcp-informix-setup`.

Recarga los MCP del cliente y prueba con `test_connection`.

### Claude Code (CLI)

El comando `setup` de este repo solo soporta `--client cursor` y `--client claude` (Claude **Desktop**). Si usas **Claude Code** (la CLI), regístralo con el comando nativo `claude mcp add`, ejecutado desde la raíz del repo:

**Linux / macOS:**

```bash
claude mcp add mysql -- $(pwd)/.venv/bin/python -m mcp_mysql
claude mcp add oracle -- $(pwd)/.venv/bin/python -m mcp_oracle
claude mcp add postgresql -- $(pwd)/.venv/bin/python -m mcp_postgresql
claude mcp add sqlserver -- $(pwd)/.venv/bin/python -m mcp_sqlserver
claude mcp add informix -- $(pwd)/.venv/bin/python -m mcp_informix
```

**Windows (PowerShell):**

```powershell
claude mcp add mysql -- "$PWD\.venv\Scripts\python.exe" -m mcp_mysql
claude mcp add oracle -- "$PWD\.venv\Scripts\python.exe" -m mcp_oracle
claude mcp add postgresql -- "$PWD\.venv\Scripts\python.exe" -m mcp_postgresql
claude mcp add sqlserver -- "$PWD\.venv\Scripts\python.exe" -m mcp_sqlserver
claude mcp add informix -- "$PWD\.venv\Scripts\python.exe" -m mcp_informix
```

Registra solo los motores que vayas a usar (necesitas las credenciales correspondientes ya cargadas en `.env`). Ejecuta los comandos desde la raíz del repo; si no, reemplaza `$(pwd)` / `$PWD` por la ruta absoluta al proyecto.

Verifica con:

```bash
claude mcp list
```

Y quita un servidor mal configurado con:

```bash
claude mcp remove <nombre>
```

Luego prueba con la tool `test_connection` dentro de una sesión de Claude Code.

### Oracle: varias conexiones (perfiles)

Un solo MCP `oracle` puede apuntar a varias bases. En `.env`:

```env
Multi Connection

ORACLE_CONNECTIONS=B1,B2
ORACLE_DEFAULT=B1

ORACLE_B1_USER=
ORACLE_B1_PASSWORD=
ORACLE_B1_HOST=
ORACLE_B1_PORT=
ORACLE_B1_SID=

ORACLE_B2_USER=
ORACLE_B2_PASSWORD=
ORACLE_B2_HOST=
ORACLE_B2_PORT=  
ORACLE_B2_SID=

```

Uso en tools: `list_connections`, luego `list_tables(connection="qa")`, `execute_query(..., connection="qa")`, etc.  
Si omites `connection`, se usa `ORACLE_DEFAULT`.

El modo simple (una sola DB) sigue funcionando con `ORACLE_USER` / `ORACLE_DSN` sin `ORACLE_CONNECTIONS`.

| Cliente | Archivo por defecto |
|---------|---------------------|
| Cursor Windows| `\Users\username\.cursor`  |
| Cursor Linux| `/home/user/.cursor/mcp.json`  |
| Gemini Windows | `C:\users\user_name\.gemini\config\mcp_config.json`  |
| Gemini Linux | `/home/username/.gemini/config/mcp_config.json`  |
| Claude Desktop Windows | `%APPDATA%\Claude\claude_desktop_config.json`  |
| Claude Desktop macOS/Linux | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `~/.config/Claude/claude_desktop_config.json` (Linux)  |

> **Claude Code (CLI):** no uses `--client claude` para esto — ese modo apunta a Claude Desktop, no a Claude Code. Usa `claude mcp add` como se explica en la sección [Claude Code (CLI)](#claude-code-cli) arriba.

## Tools disponibles

Las mismas tools en los cinco servidores (solo lectura):

| Tool | Descripción |
|------|-------------|
| `list_connections` | Lista perfiles Oracle configurados (solo Oracle por ahora) |
| `test_connection` | Verifica la conexión |
| `list_tables` | Lista tablas |
| `list_views` | Lista vistas |
| `describe_table` | Columnas de una tabla |
| `list_indexes` | Índices de una tabla |
| `list_foreign_keys` | FKs de una tabla o de toda la DB |
| `find_column` | Busca columnas por nombre (`%` wildcard) |
| `sample_rows` | Muestra filas de ejemplo (máx. 100) |
| `count_rows` | Cuenta filas de una tabla |
| `execute_query` | SQL libre de solo lectura |

**MySQL / PostgreSQL:** `SELECT`, `SHOW`/`EXPLAIN` donde aplique, `WITH` (usa `LIMIT`).

**Oracle / SQL Server / Informix:** `SELECT` / `WITH` (límites con `FETCH FIRST` / `TOP` / `FIRST`).

`execute_query` rechaza múltiples sentencias (`;`) y keywords de escritura (`INSERT`, `UPDATE`, `DELETE`, `DROP`, etc.). En producción usa además un usuario DB read-only.

### Reportes fijos (solo MySQL)

Para reportes que siempre deben ejecutar la misma query (y no una armada por el modelo), el servidor MySQL expone tools que leen el SQL desde `resources/querys/`:

| Tool | Query | Parámetros |
|------|-------|------------|
| `report_hours` | `resources/querys/hours.sql` | `desde`, `hasta` en formato `YYYYMMDD` (ej. `20260101`, `20260826`) |

- El SQL se lee del archivo en cada llamada: si editas `hours.sql`, el cambio aplica sin reiniciar el MCP.
- `hours.sql` usa los marcadores `%(desde)s` y `%(hasta)s`; no se puede pegar tal cual en otro cliente SQL. Para eso está `hours.original.sql` (con fechas fijas).
- Estos reportes no pasan por el validador de `execute_query` (la query usa la función `REPLACE()`) ni se recortan con `LIMIT`.

## Notas

- Los comandos `python -m mcp_*` arrancan el servidor stdio; lo lanza el cliente.
- Las credenciales viven en `.env`, no en el JSON del cliente.
- MySQL, Oracle y PostgreSQL no requieren instalador de driver aparte (en el flujo típico).
- SQL Server e Informix **sí** requieren driver/SDK instalado en el sistema además de `pyodbc`.

## Estructura

```
MCP-DATABASE/
├── pyproject.toml
├── .env.example
├── src/
│   ├── mcp_mysql/
│   ├── mcp_oracle/
│   ├── mcp_postgresql/
│   ├── mcp_sqlserver/
│   └── mcp_informix/
├── resources/
│   └── querys/          # SQL de reportes fijos (ej. hours.sql)
└── README.md
```

## Prueba

  ![Image Test](/img/test.png)