PostgreSQL MCP Server

Um servidor MCP que fornece ferramentas para interagir com bancos de dados PostgreSQL.

Documentação

Servidor MCP PostgreSQL

Um servidor Model Context Protocol (MCP) que fornece ferramentas para interagir com bancos de dados PostgreSQL. Construído usando o Kotlin MCP SDK oficial para conformidade robusta e padronizada com o protocolo.

Recursos

🔒 Execução Segura de Consultas: Apenas consultas SELECT são permitidas por segurança
🗄️ Inspeção de Esquema: Obtenha esquemas detalhados de tabelas e informações de colunas
📋 Listagem de Tabelas: Liste todas as tabelas no banco de dados
🔗 Descoberta de Relacionamentos: Descubra chaves estrangeiras, chaves primárias e relacionamentos entre tabelas
🔄 Sugestões de JOIN: Obtenha sugestões inteligentes de consultas JOIN baseadas em relacionamentos
🌍 Suporte a Múltiplos Ambientes: Conecte-se a bancos de dados de staging, release e produção
⚡ Pool de Conexões HikariCP: Gerenciamento de conexões de nível empresarial
📊 Monitoramento em Tempo Real: Estatísticas integradas do pool de conexões e monitoramento de saúde

Pré-requisitos

Java 17 ou superior
Banco(s) de dados PostgreSQL
Arquivo de configuração do banco de dados (database.properties)

Ferramentas Disponíveis

Nome da Ferramenta	Descrição	Parâmetros Obrigatórios	Parâmetros Opcionais	Retornos
`postgres_query`	Executa consultas SELECT no banco de dados	`sql` (string)	`environment` (staging/release/production)	Resultados da consulta em formato de tabela
`postgres_list_tables`	Lista todas as tabelas no banco de dados	Nenhum	`environment` (staging/release/production)	Lista de nomes de tabelas
`postgres_get_table_schema`	Obtém informações detalhadas de esquema para uma tabela	`table_name` (string)	`environment` (staging/release/production)	Detalhes das colunas com tipos de dados, restrições e indicadores de relacionamento
`postgres_get_relationships`	Obtém relacionamentos de tabela (FK, PK, restrições)	`table_name` (string)	`environment` (staging/release/production)	Chaves primárias, chaves estrangeiras, referenciado por, restrições únicas
`postgres_suggest_joins`	Sugere consultas JOIN baseadas em relacionamentos	`table_name` (string)	`environment` (staging/release/production)	Condições JOIN sugeridas e consultas de exemplo
`postgres_get_database_info`	Obtém nome do banco de dados e informações de conexão	Nenhum	`environment` (staging/release/production)	Nome do banco de dados, versão, informações do driver e detalhes de conexão
`postgres_connection_stats`	Obtém estatísticas do pool de conexões e informações de saúde	Nenhum	Nenhum	Status do pool HikariCP, métricas e informações de saúde

Recursos de Segurança

🔒 Acesso Somente Leitura: Apenas consultas SELECT são permitidas
🛡️ Proteção contra Injeção de SQL: Usa consultas parametrizadas quando possível
📏 Limitação de Linhas: Limites configuráveis evitam respostas sobrecarregadas
✅ Validação de Conexão: Teste e validação de conexão integrados

Configuração

Crie um arquivo database.properties em src/main/resources/ com os detalhes da sua conexão de banco de dados:

# PostgreSQL Database Configuration
# All sensitive information should be provided via environment variables

# Staging Environment
database.staging.jdbc-url=${POSTGRES_STAGING_JDBC_URL}
database.staging.username=${POSTGRES_STAGING_USERNAME}
database.staging.password=${POSTGRES_STAGING_PASSWORD}

# Release Environment
database.release.jdbc-url=${POSTGRES_RELEASE_JDBC_URL}
database.release.username=${POSTGRES_RELEASE_USERNAME}
database.release.password=${POSTGRES_RELEASE_PASSWORD}

# Production Environment
database.production.jdbc-url=${POSTGRES_PRODUCTION_JDBC_URL}
database.production.username=${POSTGRES_PRODUCTION_USERNAME}
database.production.password=${POSTGRES_PRODUCTION_PASSWORD}

# HikariCP Connection Pool Configuration (Optional)
# Uses sensible defaults if not specified

# Optional: Override default pool sizes per environment
hikari.staging.maximum-pool-size=5
hikari.staging.minimum-idle=1

hikari.release.maximum-pool-size=8
hikari.release.minimum-idle=2

hikari.production.maximum-pool-size=15
hikari.production.minimum-idle=3

Configuração de Variáveis de Ambiente

Defina as variáveis de ambiente necessárias para suas conexões de banco de dados:

# Staging Environment
export POSTGRES_STAGING_JDBC_URL="jdbc:postgresql://localhost:5432/mydb_staging"
export POSTGRES_STAGING_USERNAME="your_staging_username"
export POSTGRES_STAGING_PASSWORD="your_staging_password"

# Release Environment
export POSTGRES_RELEASE_JDBC_URL="jdbc:postgresql://localhost:5432/mydb_release"
export POSTGRES_RELEASE_USERNAME="your_release_username"
export POSTGRES_RELEASE_PASSWORD="your_release_password"

# Production Environment
export POSTGRES_PRODUCTION_JDBC_URL="jdbc:postgresql://prod-host:5432/mydb_production"
export POSTGRES_PRODUCTION_USERNAME="your_production_username"
export POSTGRES_PRODUCTION_PASSWORD="your_production_password"

Para Windows (PowerShell):

$env:POSTGRES_STAGING_JDBC_URL="jdbc:postgresql://localhost:5432/mydb_staging"
$env:POSTGRES_STAGING_USERNAME="your_staging_username"
$env:POSTGRES_STAGING_PASSWORD="your_staging_password"
# ... repeat for release and production

Para ambientes Docker/Container:

environment:
  - POSTGRES_STAGING_JDBC_URL=jdbc:postgresql://localhost:5432/mydb_staging
  - POSTGRES_STAGING_USERNAME=your_staging_username
  - POSTGRES_STAGING_PASSWORD=your_staging_password

Compilação

O sistema de compilação requer um parâmetro jarSuffix para criar arquivos JAR específicos do banco de dados:

# Build JAR for specific database system
./gradlew shadowJar -PjarSuffix=incidents
./gradlew shadowJar -PjarSuffix=users
./gradlew shadowJar -PjarSuffix=analytics
./gradlew shadowJar -PjarSuffix=payroll

Isso cria arquivos JAR com nomes descritivos:

build/libs/postgres-mcp-tool-incidents.jar
build/libs/postgres-mcp-tool-users.jar
build/libs/postgres-mcp-tool-analytics.jar
build/libs/postgres-mcp-tool-payroll.jar

Nota: O parâmetro jarSuffix é obrigatório. Executar ./gradlew shadowJar sem ele falhará com uma mensagem de erro clara.

Fluxo de Trabalho com Múltiplos Bancos de Dados

Esta convenção de nomenclatura permite gerenciar múltiplos sistemas de banco de dados de forma eficiente:

Configure seu database.properties para o sistema de banco de dados alvo
Compile o JAR com um sufixo descritivo: ./gradlew shadowJar -PjarSuffix=incidents
Repita para outros sistemas de banco de dados (usuários, analytics, folha de pagamento, etc.)
Implante múltiplos servidores MCP, cada um com seu próprio JAR e configuração de banco de dados
Diferencie facilmente entre diferentes conexões de banco de dados em seu agente de IA

Exemplo de Fluxo de Trabalho:

# Configure database.properties for incidents database
# Build incidents JAR
./gradlew shadowJar -PjarSuffix=incidents

# Update database.properties for users database
# Build users JAR
./gradlew shadowJar -PjarSuffix=users

# Update database.properties for analytics database
# Build analytics JAR
./gradlew shadowJar -PjarSuffix=analytics

Roteamento de Banco de Dados Baseado em Ambiente

Todas as ferramentas suportam roteamento de banco de dados baseado em ambiente com um parâmetro opcional environment:

staging (padrão) - Roteia para o banco de dados de staging
release - Roteia para o banco de dados de release
production - Roteia para o banco de dados de produção

Suporte a Linguagem Natural

Agentes de IA extraem automaticamente informações de ambiente dos prompts do usuário:

"Consulte o banco de dados de produção para estatísticas de usuários" → environment: "production"
"Liste tabelas no staging" → environment: "staging"
"Mostre-me o esquema da tabela de usuários no release" → environment: "release"

Uso com Agentes de IA

Adicione esta configuração ao arquivo de configuração MCP do seu agente de IA:

Configuração do Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "postgres-incidents": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-incidents.jar"]
    },
    "postgres-users": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-users.jar"]
    },
    "postgres-analytics": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-analytics.jar"]
    }
  }
}

Configuração de Banco de Dados Único:

{
  "mcpServers": {
    "postgres-mcp-tool": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-incidents.jar"]
    }
  }
}

Configuração do Plugin Augment IntelliJ

No plugin Augment IntelliJ, adicione servidores MCP para cada sistema de banco de dados:

Para Banco de Dados de Incidentes:

Nome: postgres-incidents
Comando: java -jar /absolute/path/to/postgres-mcp-tool-incidents.jar

Para Banco de Dados de Usuários:

Nome: postgres-users
Comando: java -jar /absolute/path/to/postgres-mcp-tool-users.jar

Para Banco de Dados de Analytics:

Nome: postgres-analytics
Comando: java -jar /absolute/path/to/postgres-mcp-tool-analytics.jar

Outros Agentes de IA

Para outros agentes de IA compatíveis com MCP, use o formato padrão de configuração do servidor MCP:

Múltiplos Sistemas de Banco de Dados:

[
  {
    "name": "postgres-incidents",
    "command": "java",
    "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-incidents.jar"],
    "env": {}
  },
  {
    "name": "postgres-users",
    "command": "java",
    "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-users.jar"],
    "env": {}
  }
]

Sistema de Banco de Dados Único:

{
  "name": "postgres-mcp-tool",
  "command": "java",
  "args": ["-jar", "/absolute/path/to/postgres-mcp-tool-incidents.jar"],
  "env": {}
}

Pré-requisitos

Antes de usar o servidor MCP, certifique-se de ter:

Java 17+ instalado e disponível no seu PATH
Compilado o arquivo JAR usando ./gradlew shadowJar -PjarSuffix=<database-name>
Definido as variáveis de ambiente para suas conexões de banco de dados (veja Configuração de Variáveis de Ambiente acima)
Permissões de banco de dados - o usuário configurado deve ter permissões SELECT nos bancos de dados alvo

Gerenciamento de JAR Específico do Banco de Dados

Como você pode criar múltiplos arquivos JAR para diferentes sistemas de banco de dados, você pode:

Compilar JARs separados para cada sistema de banco de dados (incidentes, usuários, analytics, etc.)
Configurar diferentes database.properties para cada sistema antes de compilar
Implantar múltiplos servidores MCP simultaneamente, cada um conectando-se a bancos de dados diferentes
Diferenciar facilmente entre conexões de banco de dados usando nomes de JAR descritivos

Arquitetura

Este servidor é construído usando:

Kotlin MCP SDK v0.5.0: Implementação oficial do Model Context Protocol
HikariCP: Pool de conexões JDBC de alto desempenho
PostgreSQL JDBC Driver: Conectividade com banco de dados
Kotlinx Serialization: Manipulação de JSON
Kotlinx Coroutines: Operações assíncronas

Gerenciamento de Conexões (HikariCP)

Pool de Nível Empresarial: Gerenciamento de conexões testado em batalha
Monitoramento Automático de Saúde: Validação de conexão e verificações de saúde integradas
Detecção de Vazamento de Conexão: Detecta e relata automaticamente vazamentos de conexão
Desempenho Otimizado: Pool de conexões mais rápido disponível para Java/Kotlin
Operações Thread-Safe: Acesso concorrente é gerenciado adequadamente

Exemplo de Uso

Exploração Básica do Banco de Dados

"A qual banco de dados estou conectado?"
"Quais tabelas existem no meu banco de dados?"
"Mostre-me o esquema da tabela de usuários"
"Consulte as primeiras 10 linhas da tabela de produtos"

Consultas Específicas por Ambiente

"Quais tabelas existem no banco de dados de produção?"
"Consulte o banco de dados de staging para estatísticas de usuários"
"Mostre-me o esquema da tabela de pedidos no ambiente de release"
"Obtenha relacionamentos para a tabela de usuários no staging"

Descoberta de Relacionamentos

"Quais são os relacionamentos da tabela de pedidos?"
"Mostre-me todas as chaves estrangeiras na tabela de clientes"
"Quais tabelas referenciam a tabela de usuários?"
"Quais consultas JOIN posso escrever com a tabela de pedidos?"

Análise Avançada de Esquema

"Mostre-me o esquema completo com relacionamentos para a tabela de produtos"
"Quais são as chaves primárias e estrangeiras de todas as minhas tabelas?"
"Ajude-me a entender como minhas tabelas estão conectadas"

Estrutura do Projeto

postgres-mcp-tool/
├── src/
│   ├── main/
│   │   ├── kotlin/
│   │   │   ├── PostgreSqlMcpServer.kt         # Main MCP server implementation
│   │   │   ├── PostgreSqlRepository.kt        # Database operations and queries
│   │   │   ├── HikariConnectionManager.kt     # Connection pool management
│   │   │   └── DatabaseConnectionConfig.kt    # Database configuration DTO
│   │   └── resources/
│   │       └── database.properties            # Database configuration
│   └── test/kotlin/
│       ├── PostgreSqlMcpServerTest.kt         # Integration tests
│       ├── DatabaseConnectionConfigTest.kt    # DTO unit tests
│       └── DatabaseConfigurationTest.kt       # Configuration integration tests
├── build.gradle.kts                           # Build configuration
├── docker-compose.yml                         # Docker setup for testing
├── init.sql                                   # Sample database schema
└── README.md                                 # This documentation

Solução de Problemas

Problemas Comuns

Falha na Conexão:
- Verifique se todas as variáveis de ambiente necessárias estão definidas
- Verifique o formato da URL JDBC: jdbc:postgresql://host:port/database
- Certifique-se de que as credenciais do banco de dados estão corretas
Variáveis de Ambiente Não Encontradas:
- Verifique se as variáveis de ambiente estão exportadas no seu shell
- Para agentes de IA, certifique-se de que as variáveis de ambiente estão disponíveis para o processo Java
Permissão Negada: Certifique-se de que o usuário do banco de dados tem permissões SELECT
Ferramenta Não Aparece: Verifique o caminho do JAR na configuração MCP do seu agente de IA
Java Não Encontrado: Certifique-se de que Java 17+ está instalado e no seu PATH
Falha na Compilação - jarSuffix Ausente:
- Use ./gradlew shadowJar -PjarSuffix=<database-name> em vez de ./gradlew shadowJar
- O parâmetro jarSuffix é obrigatório para criar nomes de JAR descritivos
Conexão de Banco de Dados Errada:
- Verifique se você está usando o arquivo JAR correto para o sistema de banco de dados pretendido
- Verifique se o nome do arquivo JAR corresponde ao seu sistema de banco de dados (ex.: postgres-mcp-tool-incidents.jar para banco de dados de incidentes)

Depuração

Verifique os logs do seu agente de IA para erros. Por exemplo:

Claude Desktop:

# macOS/Linux
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
# Check %APPDATA%\Claude\Logs\

Outros Agentes de IA:

Verifique a documentação do seu agente de IA específico para locais de logs
Procure por mensagens de erro relacionadas a MCP no console ou arquivos de log do agente

Migração para o Kotlin MCP SDK

🎉 Atualizado: Este servidor foi migrado de uma implementação JSON-RPC personalizada para usar o Kotlin MCP SDK oficial, fornecendo:

Benefícios da Migração

Melhor Conformidade com o Protocolo: Adesão total à especificação MCP
Tratamento de Erros Aprimorado: Respostas de erro padronizadas e melhor depuração
Estrutura de Código Mais Limpa: Base de código mais sustentável e legível
Compatibilidade à Prova de Futuro: Atualizações automáticas com mudanças no protocolo MCP
Desempenho Aprimorado: Camada de transporte otimizada e manipulação de mensagens

O Que Mudou

Implementação do Servidor: Agora usa a classe Server do SDK oficial
Registro de Ferramentas: Ferramentas são registradas usando o método server.addTool()
Camada de Transporte: Usa StdioServerTransport com integração adequada com kotlinx.io
Manipulação de Mensagens: Tratamento automático do protocolo JSON-RPC pelo SDK

O Que Permaneceu Igual

Toda a funcionalidade existente: Cada ferramenta e recurso foi preservado
Operações de banco de dados: Gerenciamento de conexões HikariCP inalterado
Configuração: database.properties limpo com formato simplificado
Compatibilidade de API: Todos os parâmetros e respostas de ferramentas permanecem idênticos

Detalhes Técnicos

Versão do SDK: Usando Kotlin MCP SDK v0.5.0
Transporte: Transporte STDIO com streams kotlinx.io bufferizados
Capacidades: Ferramentas com suporte a listChanged
Tratamento de Erros: Respostas de erro MCP padronizadas

Esta migração garante que o servidor permaneça compatível com todos os clientes MCP enquanto se beneficia das melhorias do SDK oficial e atualizações futuras.

Licença

Este projeto é licenciado sob a Licença MIT.