EmmanuelBarbosaMonteiro/mcp-server-database

MCP Database Server

Servidor MCP (Model Context Protocol) para executar queries em bancos de dados via agentes de IA.

🎯 Bancos Suportados

• Oracle Database - Usando oracledb
• PostgreSQL - Usando pg

💡 O servidor detecta automaticamente qual banco usar baseado nas variáveis de ambiente configuradas.

🔧 Configuração

1. Instalar dependências

npm install

2. Instalar extensões do VS Code (recomendado)

As seguintes extensões serão sugeridas automaticamente:

• ESLint - Linting e correção automática
• Prettier - Formatação de código

A formatação automática está configurada para acontecer ao salvar (Ctrl+S).

3. Configurar variáveis de ambiente

Para Oracle Database:

Crie um arquivo .env ou configure as variáveis:

# Windows PowerShell
$env:ORACLE_USER="seu_usuario"
$env:ORACLE_PASSWORD="sua_senha"
$env:ORACLE_CONNECT_STRING="localhost:1521/ORCL"
$env:ORACLE_POOL_MIN="0"
$env:ORACLE_POOL_MAX="4"

Ou no CMD:

set ORACLE_USER=seu_usuario
set ORACLE_PASSWORD=sua_senha
set ORACLE_CONNECT_STRING=localhost:1521/ORCL
set ORACLE_POOL_MIN=0
set ORACLE_POOL_MAX=4

Para PostgreSQL:

# Windows PowerShell
$env:POSTGRES_USER="seu_usuario"
$env:POSTGRES_PASSWORD="sua_senha"
$env:POSTGRES_DATABASE="nome_do_banco"
$env:POSTGRES_HOST="localhost"
$env:POSTGRES_PORT="5432"
$env:POSTGRES_POOL_MIN="0"
$env:POSTGRES_POOL_MAX="4"

Ou no CMD:

set POSTGRES_USER=seu_usuario
set POSTGRES_PASSWORD=sua_senha
set POSTGRES_DATABASE=nome_do_banco
set POSTGRES_HOST=localhost
set POSTGRES_PORT=5432
set POSTGRES_POOL_MIN=0
set POSTGRES_POOL_MAX=4

Forçar tipo de banco específico (opcional):

Se você tiver credenciais de ambos os bancos configuradas, use:

$env:DB_TYPE="oracle"    # ou "postgres"

🎨 Formatação e Linting

O projeto está configurado com ESLint e Prettier para manter a qualidade do código.

Comandos disponíveis:

# Verificar problemas de lint
npm run lint

# Corrigir problemas automaticamente
npm run lint:fix

# Formatar código
npm run format

# Verificar formatação
npm run format:check

Auto-formatação ao salvar

A formatação automática está habilitada. Ao pressionar Ctrl+S, o código será:

• ✅ Formatado pelo Prettier
• ✅ Corrigido pelo ESLint (erros automáticos)

4. Executar

Modo Desenvolvimento:

npm run dev

Modo Produção:

npm run build
npm start

🛠️ Ferramentas Disponíveis

database_query

Executa consultas SELECT no banco de dados configurado (Oracle ou PostgreSQL).

Parâmetros:

• sql (obrigatório): Query SQL SELECT
• binds (opcional): Objeto com parâmetros bind
  • Oracle: Use :paramName na query
  • PostgreSQL: Use :paramName (será convertido automaticamente para $1, $2, etc.)
• limit (opcional): Limite de linhas (padrão: 500)
• timeoutMs (opcional): Timeout em ms (padrão: 15000)

Restrições:

• Apenas queries SELECT são permitidas
• Comandos DML/DDL são bloqueados por segurança

Exemplo de uso:

{
  "sql": "SELECT * FROM users WHERE status = :status",
  "binds": { "status": "active" },
  "limit": 100
}

database_status

Retorna informações sobre o status da conexão com o banco de dados.

Retorno:

{
  "database": "Oracle",
  "connected": true,
  "poolSize": 4
}

📝 Uso com MCP Client

Adicione ao claude_desktop_config.json:

Para Oracle:

{
  "mcpServers": {
    "database": {
      "command": "node",
      "args": [
        "C:\\Users\\Emmanuel\\Desktop\\mcp\\mcp-database\\dist\\index.js"
      ],
      "env": {
        "DB_TYPE": "oracle",
        "ORACLE_USER": "seu_usuario",
        "ORACLE_PASSWORD": "sua_senha",
        "ORACLE_CONNECT_STRING": "localhost:1521/ORCL"
      }
    }
  }
}

Para PostgreSQL:

{
  "mcpServers": {
    "database": {
      "command": "node",
      "args": [
        "C:\\Users\\Emmanuel\\Desktop\\mcp\\mcp-database\\dist\\index.js"
      ],
      "env": {
        "DB_TYPE": "postgres",
        "POSTGRES_USER": "seu_usuario",
        "POSTGRES_PASSWORD": "sua_senha",
        "POSTGRES_DATABASE": "nome_do_banco",
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432"
      }
    }
  }
}

🔒 Segurança

• Nunca commite credenciais no código
• Use variáveis de ambiente ou gerenciadores de secrets
• O servidor bloqueia automaticamente comandos não-SELECT
• Bind parameters são suportados para prevenir SQL injection

🏗️ Arquitetura Extensível

O projeto foi desenvolvido com uma arquitetura modular e extensível:

• Interface IDatabaseConnector: Define o contrato para conectores de banco
• Conectores específicos: Implementações para Oracle e PostgreSQL
• Factory Pattern: Detecção e inicialização automática do banco correto
• Fácil expansão: Adicione novos bancos implementando IDatabaseConnector

Adicionar novo banco de dados:

1. Crie um novo conector em src/database/seuBancoConnector.ts
2. Implemente a interface IDatabaseConnector
3. Adicione o tipo em src/database/types.ts
4. Registre na factory em src/database/connectorFactory.ts
5. Instale as dependências necessárias