Servidor MCP de PostgreSQL

Una implementación de servidor MCP de PostgreSQL que utiliza el SDK de Python del Protocolo de Contexto de Modelo (MCP), un protocolo abierto que permite una integración fluida entre aplicaciones LLM y fuentes de datos externas. Este servidor permite a los agentes de IA interactuar con bases de datos PostgreSQL a través de una interfaz estandarizada.

Características

• Lista de esquemas de bases de datos

• Listar tablas dentro de esquemas

• Describir las estructuras de las tablas

• Lista de restricciones y relaciones de tablas

• Obtener información de clave externa

• Ejecutar consultas SQL

Related MCP server: PostgreSQL MCP Server

Inicio rápido

# Run the server without a DB connection (useful for Glama or inspection)
python postgres_server.py

# With a live database – pick one method:
export POSTGRES_CONNECTION_STRING="postgresql://user:pass@host:5432/db"
python postgres_server.py

# …or…
python postgres_server.py --conn "postgresql://user:pass@host:5432/db"

# Or using Docker (build once, then run):
# docker build -t mcp-postgres . && docker run -p 8000:8000 mcp-postgres

Instalación

Instalación mediante herrería

Para instalar PostgreSQL MCP Server para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install @gldc/mcp-postgres --client claude

Instalación manual

1. Clonar este repositorio:

git clone <repository-url>
cd mcp-postgres

2. Crear y activar un entorno virtual (recomendado):

python -m venv venv
source venv/bin/activate  # On Windows, use: venv\Scripts\activate

3. Instalar dependencias:

pip install -r requirements.txt

Uso

1. Inicie el servidor MCP.

   # Without a connection string (server starts, DB‑backed tools will return a friendly error)
   python postgres_server.py
   
   # Or set the connection string via environment variable:
   export POSTGRES_CONNECTION_STRING="postgresql://username:password@host:port/database"
   python postgres_server.py
   
   # Or pass it using the --conn flag:
   python postgres_server.py --conn "postgresql://username:password@host:port/database"

2. El servidor proporciona las siguientes herramientas:

• query : Ejecutar consultas SQL contra la base de datos

• list_schemas : enumera todos los esquemas disponibles

• list_tables : enumera todas las tablas en un esquema específico

• describe_table : Obtenga información detallada sobre la estructura de una tabla

• get_foreign_keys : Obtener relaciones de clave externa para una tabla

• find_relationships : descubre relaciones explícitas e implícitas para una tabla

Ejecutando con Docker

Construye la imagen:

docker build -t mcp-postgres .

Ejecute el contenedor sin una conexión de base de datos (el servidor permanece inspeccionable):

docker run -p 8000:8000 mcp-postgres

Ejecute una base de datos PostgreSQL en vivo suministrando POSTGRES_CONNECTION_STRING :

docker run \
  -e POSTGRES_CONNECTION_STRING="postgresql://username:password@host:5432/database" \
  -p 8000:8000 \
  mcp-postgres

Si se omite la variable de entorno, el servidor se inicia normalmente y todas las herramientas respaldadas por bases de datos devuelven un mensaje amigable que dice “la cadena de conexión no está configurada” hasta que usted lo proporcione.

Configuración con mcp.json

Para integrar este servidor con herramientas compatibles con MCP (como Cursor), agréguelo a su ~/.cursor/mcp.json :

{
  "servers": {
    "postgres": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "/path/to/postgres_server.py"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://username:password@host:5432/database?ssl=true"
      }
    }
  }
}

Si se omite POSTGRES_CONNECTION_STRING , el servidor aún se inicia y es completamente inspeccionable; las herramientas respaldadas por bases de datos simplemente devolverán un error informativo hasta que se proporcione la variable.

Reemplazar:

• /path/to/venv con la ruta de su entorno virtual

• /path/to/postgres_server.py con la ruta absoluta al script del servidor

Seguridad

• Nunca exponga credenciales de base de datos confidenciales en su código

• Utilice variables de entorno o archivos de configuración seguros para las cadenas de conexión de la base de datos

• Considere usar agrupación de conexiones para una mejor gestión de recursos

• Implementar controles de acceso adecuados y autenticación de usuarios

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Proyectos relacionados

• Especificación MCP

• SDK de Python para MCP

• Servidores MCP

Licencia

Licencia MIT

Derechos de autor (c) 2025 gldc

Por la presente se concede permiso, sin cargo, a cualquier persona que obtenga una copia de este software y los archivos de documentación asociados (el "Software"), para tratar el Software sin restricción, incluyendo, sin limitación, los derechos a usar, copiar, modificar, fusionar, publicar, distribuir, sublicenciar y/o vender copias del Software, y para permitir que las personas a quienes se les proporciona el Software lo hagan, sujeto a las siguientes condiciones:

El aviso de derechos de autor anterior y este aviso de permiso se incluirán en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO, ENTRE OTRAS, LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN FIN DETERMINADO Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DE LOS DERECHOS DE AUTOR SERÁN RESPONSABLES DE NINGUNA RECLAMACIÓN, DAÑOS U OTRAS RESPONSABILIDADES, YA SEA EN ACCIÓN CONTRACTUAL, EXTRACONTRACTUAL O DE OTRO TIPO, QUE SURJA DE, SE DERIVE DE O EN RELACIÓN CON EL SOFTWARE O EL USO U OTRAS RELACIONES CON EL MISMO.