PostgreSQL

Un servidor MCP para interactuar con una base de datos PostgreSQL.

Documentación

Servidor MCP de PostgreSQL

Stars Forks

中文 | Español

Un servidor de Protocolo de Contexto de Modelo (MCP) que proporciona herramientas para interactuar con una base de datos PostgreSQL. Permite a los asistentes de IA ejecutar consultas SQL, explicar sentencias, crear tablas y listar tablas de bases de datos a través del protocolo MCP.

✨ Características

Interactúa con bases de datos mediante IA: Permite a los LLM realizar operaciones de base de datos a través de un protocolo estructurado.
Conjunto de herramientas seguro: Separa las operaciones de lectura y escritura en herramientas distintas y autorizables (read_query, write_query).
Gestión de esquemas: Permite la creación de tablas (create_table) y su listado (list_tables).
Análisis de consultas: Proporciona una herramienta para analizar los planes de ejecución de consultas (explain_query).
Múltiples modos de transporte: Soporta stdio, Eventos Enviados por el Servidor (sse) y streamableHttp para una integración flexible con el cliente.
Configuración basada en entorno: Fácilmente configurable usando un archivo .env.

🛠️ Herramientas disponibles

El servidor expone las siguientes herramientas para que los clientes MCP las invoquen:

Nombre de la herramienta	Descripción	Parámetros
`read_query`	Ejecuta una consulta SQL `SELECT`.	`query` (cadena, obligatorio): La sentencia `SELECT` a ejecutar.
`write_query`	Ejecuta una consulta SQL `INSERT`, `UPDATE` o `DELETE`.	`query` (cadena, obligatorio): La sentencia `INSERT/UPDATE/DELETE` a ejecutar.
`create_table`	Ejecuta una sentencia SQL `CREATE TABLE`.	`schema` (cadena, obligatorio): La sentencia `CREATE TABLE`.
`list_tables`	Lista todas las tablas creadas por el usuario en la base de datos.	`schema` (cadena, opcional): El nombre del esquema para filtrar tablas.
`explain_query`	Devuelve el plan de ejecución para una consulta SQL dada.	`query` (cadena, obligatorio): La consulta a explicar (debe comenzar con `EXPLAIN`).

🚀 Inicio rápido

Requisitos previos

Go 1.23 o posterior
Un servidor de base de datos PostgreSQL

Instalación

Clona el repositorio:

git clone https://github.com/leixiaotian1/pgsql-mcp-server.git
cd pgsql-mcp-server

Instala las dependencias:
```
go mod download
```
Compila el servidor MCP:
```
go build -o pgsql-mcp-server
```

Configuración

El pg-mcp-server requiere que los detalles de conexión a la base de datos se proporcionen mediante variables de entorno. Crea un archivo .env en la raíz del proyecto con las siguientes variables:

DB_HOST=localhost      # PostgreSQL server host
DB_PORT=5432           # PostgreSQL server port
DB_NAME=postgres       # Database name
DB_USER=your_username  # Database user
DB_PASSWORD=your_pass  # Database password
DB_SSLMODE=disable     # SSL mode (disable, require, verify-ca, verify-full)
SERVER_MODE=stdio      # Server mode (stdio, sse, streamableHttp)

Uso

Ejecutar el servidor

./pgsql-mcp-server

Configuración de MCP

Para usar este servidor con un asistente de IA habilitado para MCP, agrega lo siguiente a tu configuración de MCP:

{
  "mcpServers": {
    "pgsql-mcp-server": {
      "command": "/path/to/pgsql-mcp-server",
      "args": [],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "postgres",
        "DB_USER": "your_username",
        "DB_PASSWORD": "your_password",
        "DB_SSLMODE": "disable",
        "SERVER_MODE": "stdio"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

IMPLEMENTACIÓN CON DOCKER

Haz clic para expandir la Guía de Implementación con Docker

Requisitos previos

Docker instalado

Pasos de implementación

Clona el proyecto

git clone https://github.com/leixiaotian1/pgsql-mcp-server.git
cd pgsql-mcp-server

Configura el archivo .env

Crea un archivo .env en el directorio raíz del proyecto. Este archivo almacena la información de conexión a la base de datos. Asegúrate de que el valor de DB_HOST coincida con el nombre del contenedor de la base de datos que iniciarás más adelante.
```
DB_HOST=postgres
DB_PORT=5432
DB_NAME=postgres
DB_USER=user
DB_PASSWORD=password
DB_SSLMODE=disable
SERVER_MODE=sse
```
Crea la red de Docker

Para permitir la comunicación entre el contenedor de la aplicación y el contenedor de la base de datos, crea una red Docker compartida. Este comando solo necesita ejecutarse una vez.
```
docker network create sql-mcp-network
```
Inicia el contenedor de la base de datos PostgreSQL

Usa este comando para iniciar un contenedor PostgreSQL y conectarlo a nuestra red.
Nota:
- --name postgres: Nombre del contenedor, debe coincidir exactamente con DB_HOST en tu archivo .env.
- --network sql-mcp-network: Conectar a la red compartida.
- -p 5432:5432: Mapea el puerto 5432 del host al puerto 5432 del contenedor. Esto significa que puedes conectarte desde tu computadora (por ejemplo, usando DBeaver) a través de localhost:5432, mientras que el contenedor de la aplicación accederá al puerto 5432 directamente a través de la red interna.
```
docker run -d \
  --name postgres \
  --network sql-mcp-network \
  -e POSTGRES_USER=user \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=postgres \
  -p 5432:5432 \
  postgres
```
Compila y ejecuta la aplicación

Ahora puedes usar los comandos del Makefile para gestionar la aplicación.
- Compilar la imagen y ejecutar el contenedor:
```
make build
make run
```
  Esto detendrá automáticamente los contenedores antiguos, compilará una nueva imagen e iniciará un nuevo contenedor.
- Ver los registros de la aplicación:
```
make logs
```
  Si ves Successfully connected to database, todo está funcionando correctamente.
- Detener la aplicación:
```
make stop
```

🔌 Modos del servidor

Puedes seleccionar el protocolo de transporte configurando la variable de entorno SERVER_MODE.

`stdio`

El servidor se comunica a través de la entrada y salida estándar. Este es el modo predeterminado y es ideal para pruebas locales o integración directa con clientes MCP basados en línea de comandos.

`sse`

El servidor se comunica usando Eventos Enviados por el Servidor (SSE). Cuando este modo está habilitado, el servidor iniciará un servicio HTTP y escuchará conexiones.

Endpoint SSE: http://localhost:8088/sse
Endpoint de mensajes: http://localhost:8088/message

`streamableHttp`

El servidor usa el transporte HTTP Streamable, un transporte HTTP más moderno y flexible para MCP.

Endpoint: http://localhost:8088/mcp

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Si encuentras algún error, tienes solicitudes de funciones o sugerencias de mejora, no dudes en enviar una Solicitud de Extracción (Pull Request) o abrir un Problema (Issue).

Haz un Fork del Proyecto.
Crea tu Rama de Características (git checkout -b feature/AmazingFeature).
Haz Commit de tus Cambios (git commit -m 'Add some AmazingFeature').
Haz Push a la Rama (git push origin feature/AmazingFeature).
Abre una Solicitud de Extracción.

📄 Licencia

Este proyecto es de código abierto y está licenciado bajo la Licencia MIT.