PostgreSQL

Um servidor MCP para interagir com um banco de dados PostgreSQL.

Documentação

Servidor MCP PostgreSQL

Stars Forks

中文 | English

Um servidor Model Context Protocol (MCP) que fornece ferramentas para interagir com um banco de dados PostgreSQL. Ele permite que assistentes de IA executem consultas SQL, expliquem declarações, criem tabelas e listem tabelas de banco de dados por meio do protocolo MCP.

✨ Recursos

Interaja com bancos de dados via IA: Permite que LLMs realizem operações de banco de dados por meio de um protocolo estruturado.
Conjunto de ferramentas seguro: Separa operações de leitura e escrita em ferramentas distintas e autorizáveis (read_query, write_query).
Gerenciamento de esquema: Permite criação de tabelas (create_table) e listagem (list_tables).
Análise de consultas: Fornece uma ferramenta para analisar planos de execução de consultas (explain_query).
Múltiplos modos de transporte: Suporta stdio, Server-Sent Events (sse) e streamableHttp para integração flexível com clientes.
Configuração baseada em ambiente: Facilmente configurável usando um arquivo .env.

🛠️ Ferramentas disponíveis

O servidor expõe as seguintes ferramentas para que clientes MCP possam invocar:

Nome da ferramenta	Descrição	Parâmetros
`read_query`	Executa uma consulta SQL `SELECT`.	`query` (string, obrigatório): A declaração `SELECT` a ser executada.
`write_query`	Executa uma consulta SQL `INSERT`, `UPDATE` ou `DELETE`.	`query` (string, obrigatório): A declaração `INSERT/UPDATE/DELETE` a ser executada.
`create_table`	Executa uma declaração SQL `CREATE TABLE`.	`schema` (string, obrigatório): A declaração `CREATE TABLE`.
`list_tables`	Lista todas as tabelas criadas pelo usuário no banco de dados.	`schema` (string, opcional): O nome do esquema para filtrar tabelas.
`explain_query`	Retorna o plano de execução para uma determinada consulta SQL.	`query` (string, obrigatório): A consulta a ser explicada (deve começar com `EXPLAIN`).

🚀 Início rápido

Pré-requisitos

Go 1.23 ou posterior
Um servidor de banco de dados PostgreSQL

Instalação

Clone o repositório:

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

Instale as dependências:
```
go mod download
```
Compile o servidor MCP:
```
go build -o pgsql-mcp-server
```

Configuração

O pg-mcp-server requer que os detalhes de conexão com o banco de dados sejam fornecidos por meio de variáveis de ambiente. Crie um arquivo .env na raiz do projeto com as seguintes variáveis:

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

Executando o servidor

./pgsql-mcp-server

Configuração do MCP

Para usar este servidor com um assistente de IA habilitado para MCP, adicione o seguinte à sua configuração 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": []
    }
  }
}

IMPLANTAÇÃO COM DOCKER

Clique para expandir o Guia de Implantação Docker

Pré-requisitos

Docker instalado

Etapas de implantação

Clone o projeto

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

Configure o arquivo .env

Crie um arquivo .env no diretório raiz do projeto. Este arquivo armazena as informações de conexão com o banco de dados. Garanta que o valor de DB_HOST corresponda ao nome do contêiner de banco de dados que você iniciará posteriormente.
```
DB_HOST=postgres
DB_PORT=5432
DB_NAME=postgres
DB_USER=user
DB_PASSWORD=password
DB_SSLMODE=disable
SERVER_MODE=sse
```
Crie a rede Docker

Para permitir a comunicação entre o contêiner da aplicação e o contêiner do banco de dados, crie uma rede Docker compartilhada. Este comando só precisa ser executado uma vez.
```
docker network create sql-mcp-network
```
Inicie o contêiner do banco de dados PostgreSQL

Use este comando para iniciar um contêiner PostgreSQL e conectá-lo à nossa rede.
Nota:
- --name postgres: Nome do contêiner, deve corresponder exatamente ao DB_HOST no seu arquivo .env.
- --network sql-mcp-network: Conecta à rede compartilhada.
- -p 5432:5432: Mapeia a porta 5432 do host para a porta 5432 do contêiner. Isso significa que você pode se conectar do seu computador (por exemplo, usando DBeaver) via localhost:5432, enquanto o contêiner da aplicação acessará a porta 5432 diretamente pela rede 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
```
Compile e execute a aplicação

Agora você pode usar comandos do Makefile para gerenciar a aplicação.
- Compile a imagem e execute o contêiner:
```
make build
make run
```
  Isso interromperá automaticamente os contêineres antigos, compilará uma nova imagem e iniciará um novo contêiner.
- Visualize os logs da aplicação:
```
make logs
```
  Se você vir Successfully connected to database, tudo está funcionando corretamente.
- Pare a aplicação:
```
make stop
```

🔌 Modos de servidor

Você pode selecionar o protocolo de transporte definindo a variável de ambiente SERVER_MODE.

`stdio`

O servidor se comunica por meio de entrada e saída padrão. Este é o modo padrão e é ideal para testes locais ou integração direta com clientes MCP baseados em linha de comando.

`sse`

O servidor se comunica usando Server-Sent Events (SSE). Quando este modo está habilitado, o servidor inicia um serviço HTTP e aguarda conexões.

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

`streamableHttp`

O servidor usa o transporte HTTP Streamable, um transporte baseado em HTTP mais moderno e flexível para MCP.

Endpoint: http://localhost:8088/mcp

🤝 Contribuição

Contribuições são bem-vindas! Se você encontrar algum bug, tiver solicitações de recursos ou sugestões de melhoria, sinta-se à vontade para enviar um Pull Request ou abrir uma Issue.

Faça um fork do projeto.
Crie sua branch de recurso (git checkout -b feature/AmazingFeature).
Faça commit das suas alterações (git commit -m 'Add some AmazingFeature').
Envie para a branch (git push origin feature/AmazingFeature).
Abra um Pull Request.

📄 Licença

Este projeto é open source e está licenciado sob a Licença MIT.