oracle-mcp-v1

# Configuration Guide - Oracle Node MCP Server This guide explains how to configure the Oracle MCP server in Cursor and Claude Desktop. ## 📋 Prerequisites - Node.js 18+ installed - Oracle Database accessible - Cursor IDE or Claude Desktop - Valid Oracle credentials ## 🚀 MCP Server Installation ### 1. Install Dependencies ```bash # In the project directory npm install ``` ### 2. Configure Environment Variables ```bash # Copy example file cp env.example .env # Edit with your credentials nano .env ``` **Example configuration (.env):** ```env # Oracle Database Configuration ORACLE_HOST=localhost ORACLE_PORT=1521 ORACLE_SERVICE_NAME=ORCL ORACLE_USER=your_username ORACLE_PASSWORD=your_password # MCP Server Configuration MCP_SERVER_NAME=oracle-monitor MCP_SERVER_VERSION=1.0.0 # Log Configuration LOG_LEVEL=info LOG_FILE=logs/oracle-mcp.log # Monitoring Configuration MONITOR_INTERVAL=300000 CRITICAL_SCHEMAS=HR,SCOTT,SYSTEM SENSITIVE_TABLES=USERS,ACCOUNTS,TRANSACTIONS # Notification Configuration NOTIFICATION_ENABLED=true NOTIFICATION_EMAIL=admin@company.com ``` ### 3. Test Connection ```bash # Test if Oracle connection is working npm run test-connection ``` ## 🔧 Cursor IDE Configuration ### 1. Locate MCP Configuration File Cursor uses the same configuration system as Claude Desktop. Locate the file: **Windows:** ``` %APPDATA%\Claude\claude_desktop_config.json ``` **macOS:** ``` ~/Library/Application Support/Claude/claude_desktop_config.json ``` **Linux:** ``` ~/.config/claude/claude_desktop_config.json ``` ### 2. Configure MCP Server Add the Oracle server configuration to the `claude_desktop_config.json` file: ```json { "mcpServers": { "oracle-monitor": { "command": "node", "args": ["C:\\path\\to\\oracle_node_mcp\\src\\index.js"], "env": { "ORACLE_HOST": "localhost", "ORACLE_PORT": "1521", "ORACLE_SERVICE_NAME": "ORCL", "ORACLE_USER": "your_username", "ORACLE_PASSWORD": "your_password", "LOG_LEVEL": "info" } } } } ``` ### 3. Complete Configuration Example ```json { "mcpServers": { "oracle-monitor": { "command": "node", "args": ["C:\\path\\to\\oracle_node_mcp\\src\\index.js"], "env": { "ORACLE_HOST": "your-oracle-host.com", "ORACLE_PORT": "1521", "ORACLE_SERVICE_NAME": "your_service", "ORACLE_USER": "your_username", "ORACLE_PASSWORD": "your_password", "MCP_SERVER_NAME": "oracle-monitor", "MCP_SERVER_VERSION": "1.0.0", "LOG_LEVEL": "info", "LOG_FILE": "logs/oracle-mcp.log", "MONITOR_INTERVAL": "300000", "CRITICAL_SCHEMAS": "HR,SCOTT,SYSTEM", "SENSITIVE_TABLES": "USERS,ACCOUNTS,TRANSACTIONS", "NOTIFICATION_ENABLED": "true", "NOTIFICATION_EMAIL": "admin@company.com" } } } } ``` ## 🔧 Claude Desktop Configuration ### 1. Locate Configuration File The Claude Desktop configuration file is located at: **Windows:** ``` %APPDATA%\Claude\claude_desktop_config.json ``` **macOS:** ``` ~/Library/Application Support/Claude/claude_desktop_config.json ``` **Linux:** ``` ~/.config/claude/claude_desktop_config.json ``` ### 2. Configure MCP Server Use the same configuration shown above for Cursor. ## 🛠️ Alternative Configuration (Using .env) ### 1. Configure Absolute Path If you prefer to use the `.env` file, configure the absolute path: ```json { "mcpServers": { "oracle-monitor": { "command": "node", "args": ["C:\\path\\to\\oracle_node_mcp\\src\\index.js"], "cwd": "C:\\path\\to\\oracle_node_mcp" } } } ``` ### 2. Use Startup Script Create a `start-mcp.bat` (Windows) or `start-mcp.sh` (Linux/macOS) script: **start-mcp.bat:** ```batch @echo off cd /d "C:\path\to\oracle_node_mcp" node src\index.js ``` **start-mcp.sh:** ```bash #!/bin/bash cd "/path/to/oracle_node_mcp" node src/index.js ``` And configure in MCP: ```json { "mcpServers": { "oracle-monitor": { "command": "C:\\path\\to\\oracle_node_mcp\\start-mcp.bat" } } } ``` ## 🔍 Configuration Verification ### 1. Check if Server is Running ```bash # In the project directory npm start ``` You should see output similar to: ``` Oracle MCP Server started successfully! ``` ### 2. Test in Cursor/Claude Desktop 1. Restart Cursor/Claude Desktop 2. Open a new conversation 3. Type: "List available Oracle tools" 4. Claude should respond with the list of MCP tools ### 3. Test Oracle Connection In Cursor/Claude Desktop, type: ``` Check the health of the Oracle database ``` ## 🐛 Troubleshooting ### Problem: Server doesn't start **Solution:** 1. Check if Node.js is installed: `node --version` 2. Check if dependencies are installed: `npm install` 3. Check Oracle credentials in `.env` file 4. Test connection: `npm run test-connection` ### Problem: Claude doesn't recognize the server **Solution:** 1. Check configuration file path 2. Check if JSON is valid 3. Restart Cursor/Claude Desktop 4. Check server logs ### Problem: Oracle connection error **Solution:** 1. Check if Oracle is running 2. Check host, port and service name 3. Check username and password 4. Check if user has necessary privileges ### Problem: Path not found **Solution:** 1. Use absolute paths 2. Check if `src/index.js` file exists 3. Use double backslashes on Windows: `C:\\path\\file.js` ## 📝 Usage Examples ### 1. Check Database Health ``` Check the health of the Oracle database ``` ### 2. List Tables from a Schema ``` List all tables from the HR schema ``` ### 3. Analyze Constraints ``` Show all foreign keys from the HR schema ``` ### 4. Check Performance ``` Analyze indexes for the EMPLOYEES table in HR schema ``` ## 🔧 Advanced Configuration ### 1. Multiple MCP Servers ```json { "mcpServers": { "oracle-monitor": { "command": "node", "args": ["C:\\path\\to\\oracle_node_mcp\\src\\index.js"], "env": { "ORACLE_HOST": "localhost", "ORACLE_PORT": "1521", "ORACLE_SERVICE_NAME": "ORCL", "ORACLE_USER": "user1", "ORACLE_PASSWORD": "password1" } }, "oracle-prod": { "command": "node", "args": ["C:\\path\\to\\oracle_node_mcp\\src\\index.js"], "env": { "ORACLE_HOST": "prod-server", "ORACLE_PORT": "1521", "ORACLE_SERVICE_NAME": "PROD", "ORACLE_USER": "user2", "ORACLE_PASSWORD": "password2" } } } } ``` ### 2. Configuration with Logs ```json { "mcpServers": { "oracle-monitor": { "command": "node", "args": ["C:\\path\\to\\oracle_node_mcp\\src\\index.js"], "env": { "ORACLE_HOST": "localhost", "ORACLE_PORT": "1521", "ORACLE_SERVICE_NAME": "ORCL", "ORACLE_USER": "your_username", "ORACLE_PASSWORD": "your_password", "LOG_LEVEL": "debug", "LOG_FILE": "logs/oracle-mcp-debug.log" } } } } ``` ## 📚 Additional Resources - [MCP Documentation](https://modelcontextprotocol.io/) - [Oracle Node.js Documentation](https://oracle.github.io/node-oracledb/) - [Cursor IDE Documentation](https://cursor.sh/docs) - [Claude Desktop Documentation](https://claude.ai/desktop) - [GitHub Repository](https://github.com/lrferr/oracle-node-mcp) --- **💡 Tip:** Always keep a backup copy of the configuration file before making changes!