Postgres MCP Server

Postgres MCP Server

Um servidor Model Context Protocol (MCP) que fornece acesso seguro a banco de dados PostgreSQL através do Kysely ORM. Este servidor permite que o Claude Desktop interaja com bancos de dados PostgreSQL usando linguagem natural.

Recursos

• Ferramentas MCP: Execução de consultas, listagem de tabelas, inspeção de esquemas e informações de restrições
• Segurança de Tipos: Suporte completo a TypeScript com entradas/saídas tipadas
• Pool de Conexões: Limites de conexão configuráveis com timeout de inatividade
• Tratamento de Erros: Mensagens de erro elegantes para problemas de conexão e consulta
• Segurança: Consultas parametrizadas para prevenir injeção de SQL

Instalação

npx postgres-mcp-server

Configuração

Crie um arquivo .env com suas credenciais de banco de dados:

DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password_here
DB_NAME=postgres
DB_SSL=true

Ferramentas Disponíveis

Ferramenta	Descrição	Parâmetros Obrigatórios	Parâmetros Opcionais
query	Executa consultas SQL com suporte a paginação	sql (string)	pageSize (1-500), offset (number), parameters (array)
describe_table	Obtém a estrutura da tabela e detalhes das colunas	schema (string), table (string)	-
list_tables	Lista todas as tabelas em um esquema	schema (string)	-
list_schemas	Lista todos os esquemas no banco de dados	-	includeSystemSchemas (boolean)
get_constraints	Obtém restrições de tabela (PK, FK, etc.)	schema (string), table (string)	-
list_indexes	Lista índices para uma tabela ou esquema	schema (string)	table (string)
list_views	Lista visualizações em um esquema	schema (string)	-
list_functions	Lista funções e procedimentos	schema (string)	-
explain_query	Obtém plano de execução de consulta	sql (string)	analyze (boolean), format (text/json/xml/yaml)
get_table_stats	Obtém tamanho da tabela e estatísticas	schema (string)	table (string)

Recursos Principais

• Paginação: A ferramenta de consulta suporta até 500 linhas por página com tratamento automático de LIMIT/OFFSET
• Segurança: Consultas parametrizadas previnem injeção de SQL, modo READ_ONLY por padrão
• Segurança de Tipos: Suporte completo a TypeScript com validação de esquema Zod

Configuração do Claude Desktop

Adicione este servidor ao seu arquivo de configuração do Claude Desktop:

Edite claude_desktop_config.json:

{
  "mcpServers": {
    "postgres-mcp-server": {
      "command": "npx",
      "args": ["postgres-mcp-server"],
      "env": {
        "DB_HOST": "127.0.0.1",
        "DB_PORT": "5432",
        "DB_USER": "postgres",
        "DB_PASSWORD": "your_password_here",
        "DB_NAME": "your_database_name",
        "DB_SSL": "true"
      }
    }
  }
}

Locais dos Arquivos de Configuração

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Desenvolvimento

# Clone and install dependencies
git clone https://github.com/abiswas97/postgres-mcp-server.git
cd postgres-mcp-server
npm install

# Run in development mode with hot reload
npm run dev

# Build for production
npm run build

# Run tests
npm run test

# Run specific test suites
npm run test:unit
npm run test:integration

Variáveis de Ambiente

Variável	Padrão	Descrição
DB_HOST	127.0.0.1	Host do PostgreSQL
DB_PORT	5432	Porta do PostgreSQL
DB_USER	postgres	Usuário do banco de dados
DB_PASSWORD	obrigatório	Senha do banco de dados
DB_NAME	postgres	Nome do banco de dados
DB_SSL	true	Habilita conexão SSL
READ_ONLY	true	Restringe a consultas SELECT/WITH/EXPLAIN
QUERY_TIMEOUT	30000	Timeout de consulta em milissegundos
MAX_PAGE_SIZE	500	Máximo de linhas por página
DEFAULT_PAGE_SIZE	100	Tamanho padrão da página quando não especificado

Licença

ISC