MCP Postgres Query Server

MCP Postgres Query Server

Uma implementação de servidor Model Context Protocol (MCP) para consultar um banco de dados PostgreSQL em modo somente leitura, projetada para funcionar com o Claude Desktop e outros clientes MCP.

Visão Geral

Este projeto implementa um servidor Model Context Protocol (MCP) que fornece:

1. Uma interface segura e somente leitura para um banco de dados PostgreSQL
2. Integração com o Claude Desktop através do protocolo MCP
3. Validação de consultas SQL para garantir que apenas consultas SELECT sejam executadas
4. Proteção de tempo limite de consulta (10 segundos)

Pré-requisitos

• Node.js (v14 ou posterior)
• npm (vem com Node.js)
• Banco de dados PostgreSQL (detalhes de conexão fornecidos via linha de comando)

Instalação

# Clone the repository
git clone https://github.com/RathodDarshil/mcp-postgres-query-server.git
cd mcp-postgres-query-server

# Install dependencies
npm install

# Build the project
npm run build

Conectando ao Claude Desktop

Você pode configurar o Claude Desktop para iniciar e conectar automaticamente ao servidor MCP:

1. Acesse o arquivo de configuração do Claude Desktop:

   • Abra o Claude Desktop
   • Vá para Configurações > Desenvolvedor > Editar Config
   • Isso abrirá o arquivo de configuração no seu editor de texto padrão

2. Adicione o postgres-query-server à seção mcpServers do seu claude_desktop_config.json:

{
    "mcpServers": {
        "postgres-query": {
            "command": "node",
            "args": [
                "/path/to/your/mcp-postgres-query-server/dist/index.js",
                "postgresql://username:password@hostname:port/database"
            ]
        }
    }
}

3. Substitua /path/to/your/ pelo caminho real do diretório do seu projeto.
4. Substitua a string de conexão PostgreSQL pelas suas credenciais reais do banco de dados.
5. Salve o arquivo e reinicie o Claude Desktop. O servidor MCP agora deve aparecer no menu suspenso de seleção de servidor MCP nas Configurações.

Exemplo de Configuração

Aqui está um exemplo completo de um arquivo de configuração com postgres-query:

{
    "mcpServers": {
        "postgres-query": {
            "command": "node",
            "args": [
                "/Users/darshilrathod/mcp-servers/mcp-postgres-query-server/dist/index.js",
                "postgresql://user:password@localhost:5432/mydatabase"
            ]
        }
    }
}

Atualizando a Configuração

Para atualizar sua configuração do Claude Desktop:

1. Abra o Claude Desktop
2. Vá para Configurações > Desenvolvedor > Editar Config
3. Faça suas alterações no arquivo de configuração
4. Salve o arquivo
5. Reinicie o Claude Desktop para que as alterações tenham efeito
6. Se você atualizou o código do servidor MCP, certifique-se de reconstruí-lo com npm run build antes de reiniciar

Recursos

• Acesso Somente Leitura ao Banco de Dados: Apenas consultas SELECT são permitidas por segurança
• Validação de Consultas: Impede operações SQL potencialmente prejudiciais
• Proteção de Tempo Limite: Consultas que excedem 10 segundos são automaticamente encerradas
• Suporte ao Protocolo MCP: Implementação completa do Model Context Protocol
• Formatação de Resposta JSON: Os resultados das consultas são retornados em formato JSON estruturado

API

Ferramentas

query-postgres

Executa uma consulta SQL somente leitura no banco de dados PostgreSQL configurado.

Parâmetros:

• query (string): Uma consulta SQL SELECT para executar

Resposta:

• Objeto JSON contendo:
  • rows: As linhas do conjunto de resultados
  • rowCount: Número de linhas retornadas
  • fields: Metadados das colunas

Exemplo:

query-postgres: SELECT * FROM users LIMIT 5

Desenvolvimento

A implementação principal do servidor está em src/index.ts. Componentes principais:

• Configuração do pool de conexões PostgreSQL
• Lógica de validação de consultas
• Configuração do servidor MCP
• Definições de ferramentas e recursos

Para modificar o comportamento do servidor, você pode:

• Editar a lógica de validação de consultas em isReadOnlyQuery()
• Adicionar ferramentas ou recursos adicionais ao servidor MCP
• Modificar a duração do tempo limite da consulta (atualmente 10 segundos)

Considerações de Segurança

• O servidor valida todas as consultas para garantir que sejam somente leitura
• A conexão com o banco de dados usa SSL
• O tempo limite da consulta evita esgotamento de recursos
• Nenhuma operação de escrita é permitida
• As credenciais do banco de dados são passadas diretamente via argumentos de linha de comando, não armazenadas em arquivos

Licença

ISC

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.