Simple PostgreSQL MCP Server

Um servidor MCP para interagir com bancos de dados PostgreSQL usando ferramentas, recursos e prompts.

Documentação

Simple PostgreSQL MCP Server

Este é um projeto modelo para aqueles que desejam construir seus próprios servidores MCP. Eu o projetei para ser extremamente simples de entender e adaptar - o código é direto com documentação MCP anexada para que você possa se atualizar rapidamente.

O que é MCP?

TL;DR - É uma maneira de escrever plugins para IA

Model Context Protocol (MCP) é uma forma padrão para LLMs interagirem com ferramentas e dados externos. Em resumo:

Ferramentas permitem que o LLM execute comandos (como executar uma consulta de banco de dados)
Recursos são dados que você pode anexar a conversas (como anexar um arquivo a um prompt)
Prompts são modelos que geram instruções consistentes para o LLM

Recursos

Este servidor MCP PostgreSQL implementa:

Ferramentas
- execute_query - Executar consultas SQL no seu banco de dados
- test_connection - Verificar se a conexão com o banco de dados está funcionando
Recursos
- db://tables - Lista de todas as tabelas no esquema
- db://tables/{table_name} - Informações de esquema para uma tabela específica
- db://schema - Informações completas de esquema para todas as tabelas no banco de dados
Prompts
- Modelos de geração de consultas
- Construtores de consultas analíticas
- Baseados nos modelos deste repositório

Pré-requisitos

Python 3.8+
uv - Gerenciador e instalador de pacotes Python moderno
npx (incluído com Node.js)
Banco de dados PostgreSQL ao qual você possa se conectar

Configuração Rápida

Crie um ambiente virtual e instale as dependências:

# Create a virtual environment with uv
uv venv

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -r requirements.txt

Execute o servidor com o MCP Inspector:
```
# Replace with YOUR actual database credentials
npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://username:password@hostname:port/database -e SCHEMA=public
```
Nota: Se esta for a primeira vez que você executa o npx, será solicitado que você aprove a instalação. Digite 'y' para continuar.

Após executar este comando, você verá a interface do MCP Inspector aberta no seu navegador. Você deverá ver uma mensagem como:
```
MCP Inspector is up and running at http://localhost:5173
```
Se o navegador não abrir automaticamente, copie e cole a URL no seu navegador. Você deverá ver algo assim:
Usando o Inspector:
- Clique no botão "Conectar" na interface (a menos que haja uma mensagem de erro no console no canto inferior esquerdo)
- Explore as abas "Ferramentas", "Recursos" e "Prompts" para ver a funcionalidade disponível
- Tente clicar nos comandos listados ou digitar nomes de recursos para recuperar recursos e prompts
- A interface permite testar consultas e ver como o servidor MCP responde
Dê uma olhada na documentação oficial

Guia oficial para desenvolvedores de servidores: https://modelcontextprotocol.io/quickstart/server

Mais sobre o inspector: https://modelcontextprotocol.io/docs/tools/inspector

Conecte Sua Ferramenta de IA ao Servidor

Você pode configurar o servidor MCP para seu assistente de IA criando um arquivo de configuração MCP:

{
   "mcpServers": {
      "postgres": {
         "command": "/path/to/uv",
         "args": [
            "--directory",
            "/path/to/simple-psql-mcp",
            "run",
            "postgres"
         ],
         "env": {
            "DSN": "postgresql://username:password@localhost:5432/my-db",
            "SCHEMA": "public"
         }
      }
   }
}

Alternativamente, você pode gerar este arquivo de configuração usando o script incluído:

# Make the script executable
chmod +x generate_mcp_config.sh

# Run the configuration generator
./generate_mcp_config.sh

Quando solicitado, insira seu DSN do PostgreSQL e o nome do esquema.

Como usar

Agora você pode fazer perguntas ao LLM sobre seus dados em linguagem natural:

"Quais são todas as tabelas no meu banco de dados?"
"Mostre-me os 5 principais usuários por data de criação"
"Conte endereços por estado"

Para testes, o Claude Desktop suporta MCP nativamente e funciona com todos os recursos (ferramentas, recursos e prompts) imediatamente.

Banco de Dados de Exemplo (Opcional)

Se você não tiver um banco de dados pronto ou encontrar problemas de conexão, pode usar o banco de dados de exemplo incluído:

# Make the script executable
chmod +x example-db/create-db.sh

# Run the database setup script
./example-db/create-db.sh

Este script cria um contêiner Docker com um banco de dados PostgreSQL pré-populado com tabelas de exemplo de usuários e endereços. Após a execução, você pode se conectar usando:

npx @modelcontextprotocol/inspector uv --directory . run postgres -e DSN=postgresql://postgres:postgres@localhost:5432/user_database -e SCHEMA=public

Próximos Passos

Para estender este projeto com seus próprios servidores MCP:

Crie um novo diretório sob /src (por exemplo, /src/my-new-mcp)
Implemente seu servidor MCP seguindo o exemplo do PostgreSQL
Adicione seu novo MCP a pyproject.toml:

[project.scripts]
postgres = "src.postgres:main"
my-new-mcp = "src.my-new-mcp:main"

Você pode então executar seu novo MCP com:

npx @modelcontextprotocol/inspector uv --directory . run my-new-mcp

Documentação

Documentação MCP incluída para facilitar o desenvolvimento de LLM
Baseado na abordagem em: https://modelcontextprotocol.io/tutorials/building-mcp-with-llms

Segurança

Este é um projeto experimental destinado a capacitar desenvolvedores a criar seu próprio servidor MCP. Fiz o mínimo para garantir que ele não falhe imediatamente quando você tentar, mas tenha cuidado - é muito fácil executar injeções de SQL com esta ferramenta. O servidor verificará se a consulta começa com SELECT, mas além disso nada é garantido. TL;DR - não execute em produção a menos que você seja o fundador e não haja clientes pagantes.

Licença

MIT