MCP Oracle Database Server

Um servidor para integração completa com o Oracle Database. Requer as bibliotecas Oracle Instant Client.

Documentação

MCP Oracle Database Server

Servidor MCP (Model Context Protocol) para integração completa com Oracle Database. Permite executar consultas SQL, comandos DDL/DML, gerenciar transações e explorar a estrutura do banco de dados diretamente de aplicações MCP.

🚀 Características

Consultas SQL: Executa SELECT com formatação inteligente de resultados
Comandos DML/DDL: INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, etc.
Gerenciamento de Transações: Suporte para transações manuais e automáticas
Exploração de BD: Lista tabelas, descreve estruturas, explora esquemas
Pool de Conexões: Gerenciamento eficiente de conexões com Oracle
Compatibilidade: Suporte para versões antigas do Oracle (pré-12c)
Monitoramento: Health checks e estatísticas de conexão

📋 Ferramentas Disponíveis

`oracle_health_check`

Verifica o estado de saúde da conexão Oracle DB.

`oracle_query`

Executa consultas SQL SELECT com formato de tabela ou JSON.

Parâmetros: sql, maxRows, formatAsTable, showMetadata

`oracle_execute`

Executa comandos SQL (INSERT, UPDATE, DELETE, CREATE, etc.).

Parâmetros: sql, autoCommit, showDetails

`oracle_list_tables`

Lista todas as tabelas do esquema especificado.

Parâmetros: owner, showDetails

`oracle_describe_table`

Mostra a estrutura completa de uma tabela.

Parâmetros: tableName, owner, showDetails

`oracle_transaction`

Executa múltiplos comandos SQL em uma transação.

Parâmetros: commands, rollbackOnError

`oracle_info`

Mostra informações de configuração da conexão.

🛠️ Instalação

⚠️ IMPORTANTE: Para Oracle 9g e versões antigas

Se você está usando Oracle 9g ou versões anteriores, deve realizar estes passos adicionais:

Configurar modo de compatibilidade:

ORACLE_OLD_CRYPTO=true

Baixar Oracle Instant Client 19.26 (obrigatório para Oracle 9g):
- Windows: instantclient-basic-windows.x64-19.26.0.0.0dbru.zip
- Extrair para uma pasta (ex: C:\oracle\instantclient_19_26)
- Configurar o caminho:

ORACLE_CLIENT_LIB_DIR=C:\oracle\instantclient_19_26

Configuração MCP para Oracle 9g:

{
  "mcpServers": {
    "oracle-db": {
      "command": "npx",
      "args": ["@grec0/mcp-oracle-db"],
      "env": {
        "ORACLE_HOST": "tu-host-oracle",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "tu-servicio",
        "ORACLE_USERNAME": "usuario",
        "ORACLE_PASSWORD": "contraseña",
        "ORACLE_OLD_CRYPTO": "true",
        "ORACLE_CLIENT_LIB_DIR": "C:\\oracle\\instantclient_19_26"
      }
    }
  }
}

Instalação Geral MCP EM LOCAL (NÃO RECOMENDADO)

Instalar dependências:

npm install

Configurar variáveis de ambiente:

cp config.example.env .env
# Editar .env con la configuración de su base de datos

Compilar:

npm run build

⚙️ Configuração

Variáveis de Ambiente

Variável	Descrição	Padrão
`ORACLE_HOST`	Host do servidor Oracle	`localhost`
`ORACLE_PORT`	Porta do Oracle	`1521`
`ORACLE_SERVICE_NAME`	Nome do serviço Oracle	`XE`
`ORACLE_USERNAME`	Usuário do banco de dados	`hr`
`ORACLE_PASSWORD`	Senha do banco de dados	`hr`
`ORACLE_CONNECTION_STRING`	Connection string completo (alternativo)	-
`ORACLE_OLD_CRYPTO`	OBRIGATÓRIO para Oracle 9g - Usar modo Thick	`false`
`ORACLE_CLIENT_LIB_DIR`	OBRIGATÓRIO para Oracle 9g - Caminho para Instant Client 19.26	-
`ORACLE_POOL_MIN`	Conexões mínimas do pool	`1`
`ORACLE_POOL_MAX`	Conexões máximas do pool	`10`
`ORACLE_POOL_TIMEOUT`	Timeout do pool em segundos	`60`
`ORACLE_FETCH_SIZE`	Linhas a buscar por lote	`100`
`ORACLE_STMT_CACHE_SIZE`	Tamanho do cache de statements	`30`

Configuração MCP em Aplicações USANDO NPX (RECOMENDADO)

Localização do arquivo de configuração

Claude Desktop:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Para Claude Desktop (config.json)

Configuração para Oracle 9g (com Instant Client 19.26):

{
  "mcpServers": {
    "oracle-db": {
      "command": "npx",
      "args": ["@grec0/mcp-oracle-db"],
      "env": {
        "ORACLE_HOST": "tu-host-oracle",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "tu-servicio",
        "ORACLE_USERNAME": "usuario",
        "ORACLE_PASSWORD": "contraseña",
        "ORACLE_OLD_CRYPTO": "true",
        "ORACLE_CLIENT_LIB_DIR": "C:\\oracle\\instantclient_19_26"
      }
    }
  }
}

Configuração para Oracle 12c ou superior:

{
  "mcpServers": {
    "oracle-db": {
      "command": "npx",
      "args": ["@grec0/mcp-oracle-db"],
      "env": {
        "ORACLE_HOST": "host",
        "ORACLE_PORT": "port",
        "ORACLE_SERVICE_NAME": "service",
        "ORACLE_USERNAME": "user",
        "ORACLE_PASSWORD": "password"
      }
    }
  }
}

Para instalação local

{
  "mcpServers": {
    "oracle-db": {
      "command": "node",
      "args": ["C:/workspaces/mcps/mcp-oracle-db/dist/index.js"],
      "env": {
        "ORACLE_HOST": "host",
        "ORACLE_PORT": "post",
        "ORACLE_SERVICE_NAME": "service",
        "ORACLE_USERNAME": "user",
        "ORACLE_PASSWORD": "pass",
        "ORACLE_OLD_CRYPTO": "true"
      }
    }
  }
}

Para ambiente de desenvolvimento

{
  "mcpServers": {
    "oracle-db": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "C:/workspaces/mcps/mcp-oracle-db",
      "env": {
        "ORACLE_HOST": "localhost",
        "ORACLE_PORT": "1521", 
        "ORACLE_SERVICE_NAME": "XE",
        "ORACLE_USERNAME": "hr",
        "ORACLE_PASSWORD": "hr"
      }
    }
  }
}

Verificar configuração MCP

Depois de configurar o MCP, você pode verificar se funciona corretamente:

Reiniciar a aplicação (Claude Desktop, etc.)
Usar ferramenta de diagnóstico:
```
oracle_health_check()
```
Testar consulta básica:
```
oracle_query("SELECT 1 FROM DUAL")
```

Variáveis de Ambiente Principais

# Configuración básica
ORACLE_HOST=localhost
ORACLE_PORT=1521
ORACLE_SERVICE_NAME=XE
ORACLE_USERNAME=hr
ORACLE_PASSWORD=hr

# O usar connection string completo
ORACLE_CONNECTION_STRING="(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=XE)))"

# Para versiones antiguas de Oracle (pre-11g)
ORACLE_OLD_CRYPTO=true
ORACLE_CLIENT_LIB_DIR=/path/to/instantclient

Configuração Baseada em Java Existente

Baseado na configuração Java fornecida:

ORACLE_HOST=host
ORACLE_PORT=port
ORACLE_SERVICE_NAME=service
ORACLE_USERNAME=user
ORACLE_PASSWORD=password
ORACLE_OLD_CRYPTO=true
ORACLE_FETCH_SIZE=100  # Basado en DataSourceCrmConfig.java

Pool de Conexões

ORACLE_POOL_MIN=2
ORACLE_POOL_MAX=10
ORACLE_POOL_INCREMENT=1
ORACLE_POOL_TIMEOUT=60
ORACLE_STMT_CACHE_SIZE=30

🚀 Uso

Iniciar o servidor

npm run start

Modo desenvolvimento

npm run dev

Com inspector MCP

npm run inspector

📚 Exemplos de Uso

Consulta Simples

SELECT * FROM employees WHERE department_id = 10

Criar Tabela

CREATE TABLE test_table (
    id NUMBER PRIMARY KEY,
    name VARCHAR2(100) NOT NULL,
    created_date DATE DEFAULT SYSDATE
)

Inserir Dados

INSERT INTO test_table (id, name) VALUES (1, 'Test Record')

Transação Complexa

-- Comando 1
INSERT INTO customers (id, name) VALUES (1, 'Cliente Test');
-- Comando 2  
UPDATE orders SET customer_id = 1 WHERE id = 100;
-- Comando 3
DELETE FROM temp_data WHERE processed = 'Y';

🔧 Solução de Problemas

⚠️ Erro Oracle 9g: Password Verifier Not Supported

Se você obtiver o erro "password verifier type 0x939 is not supported by node-oracledb in Thin mode" com Oracle 9g:

Solução OBRIGATÓRIA para Oracle 9g:

📦 Passo 1: Baixar Oracle Instant Client 19.26

# Descargar desde:
# https://download.oracle.com/otn_software/nt/instantclient/1926000/instantclient-basic-windows.x64-19.26.0.0.0dbru.zip

# Extraer a:
C:\oracle\instantclient_19_26

⚙️ Passo 2: Configurar variáveis obrigatórias

ORACLE_OLD_CRYPTO=true
ORACLE_CLIENT_LIB_DIR=C:\oracle\instantclient_19_26

🚀 Para versões Oracle 10g-11g: Testar sem Instant Client primeiro

ORACLE_OLD_CRYPTO=true

📦 Se falhar com 10g-11g, instalar Oracle Instant Client

Baixar Oracle Instant Client:
- Windows: Oracle Instant Client para Windows
- Linux: Oracle Instant Client para Linux
- macOS: Oracle Instant Client para macOS
Configurar o caminho:

ORACLE_CLIENT_LIB_DIR=/path/to/instantclient

📋 Exemplos de configuração:

Configuração básica (testar primeiro):

ORACLE_HOST=your-oracle-host
ORACLE_PORT=1521
ORACLE_SERVICE_NAME=your-service
ORACLE_USERNAME=username
ORACLE_PASSWORD=password
ORACLE_OLD_CRYPTO=true

Configuração com Instant Client (se necessário):

ORACLE_HOST=your-oracle-host
ORACLE_PORT=1521
ORACLE_SERVICE_NAME=your-service
ORACLE_USERNAME=username
ORACLE_PASSWORD=password
ORACLE_OLD_CRYPTO=true
ORACLE_CLIENT_LIB_DIR=/opt/oracle/instantclient_19_8

❓ O que é Oracle Instant Client?

Oracle Instant Client são bibliotecas nativas que permitem conexões Thick (mais compatíveis com Oracle antigo).

Quando é necessário?

✅ NÃO necessário: Se seu Oracle for 12c ou superior
⚠️ Pode ser necessário: Para Oracle 10g/11g com crypto antigo
❌ Obrigatório: Para funções avançadas (LDAP, conexões wallet, etc.)

Como saber se preciso?

Teste primeiro apenas com ORACLE_OLD_CRYPTO=true
Se obtiver erros, então instale Oracle Instant Client

📦 Instalação do Oracle Instant Client (Somente se necessário)

Windows:

Baixar "Basic Package" de Oracle Downloads
Extrair para C:\oracle\instantclient_XX_Y
Configurar: ORACLE_CLIENT_LIB_DIR=C:\oracle\instantclient_XX_Y

Linux:

# Ubuntu/Debian
wget https://download.oracle.com/otn_software/linux/instantclient/XXX/instantclient-basic-linux.x64-XX.Y.Z.zip
unzip instantclient-basic-linux.x64-XX.Y.Z.zip
export ORACLE_CLIENT_LIB_DIR=/opt/oracle/instantclient_XX_Y

macOS:

# Descargar desde Oracle y extraer
export ORACLE_CLIENT_LIB_DIR=/opt/oracle/instantclient_XX_Y

Erro de Conexão TNS

Verificar:

Host e porta corretos
Serviço/SID configurado
Firewall/conectividade de rede
Listener do Oracle em execução

Problemas de Pool

# Ajustar configuración del pool
ORACLE_POOL_MIN=1
ORACLE_POOL_MAX=5
ORACLE_POOL_TIMEOUT=30

🧪 Testes

npm test

📖 Compatibilidade

Oracle Database: 11g, 12c, 18c, 19c, 21c
Node.js: >=18.0.0
Sistemas: Windows, Linux, macOS

🔐 Segurança

Validação de SQL para prevenir injeções básicas
Gerenciamento seguro de credenciais via variáveis de ambiente
Suporte para conexões SSL/TLS do Oracle
Separação de permissões entre consultas e comandos

🤝 Contribuição

Fork o projeto
Criar branch para feature (git checkout -b feature/nueva-funcionalidad)
Commit das alterações (git commit -am 'Agregar nueva funcionalidad')
Push para o branch (git push origin feature/nueva-funcionalidad)
Criar Pull Request

📄 Licença

MIT License - veja LICENSE para mais detalhes.

🆘 Suporte

Para reportar problemas ou solicitar recursos:

GitHub Issues: github.com/gcorroto/mcp-oracle-db/issues

MCP Oracle Database Server

Documentação