OracleMcp 1.0.1

Oracle MCP Server

A Model Context Protocol (MCP) server that gives AI assistants direct, read-only access to Oracle databases. Built with .NET 10 and distributed as a NuGet global tool.

Features

Tool	Description
query	Execute read-only SQL SELECT statements with parameterized bind variables. All data modification statements are blocked.
describe	Inspect table structure including columns, data types, primary keys, foreign keys, indexes, and approximate row count.
search-tables	Discover tables by business term. Searches table and column names, ranks results by relevance, and reports approximate row counts.
business-dictionary	Look up semantic descriptions and domain value mappings from a user-provided dictionary file, helping interpret coded columns and status values.

How the Tools Work Together

1. search-tables("employee")        → find the right table
2. describe("EMPLOYEES")            → understand columns, PKs, indexes
3. query("SELECT ... FROM ...")     → write an optimized query on the first attempt

The AI agent uses search-tables to discover tables, describe to understand their structure, and query to fetch data. The business-dictionary enriches describe and search-tables results with human-readable context when available.

Safety

• Only SELECT statements are allowed; INSERT, UPDATE, DELETE, DROP, and DDL are rejected before reaching the database.
• Query timeout and row limits are configurable to prevent runaway queries.

---

Prerequisites

• .NET 10 SDK or later
• Access to an Oracle database (hostname, port, service name or SID, credentials)
• An MCP-compatible client (Claude Code, Claude Desktop, VS Code with Copilot, etc.)

To verify .NET is installed:

dotnet --version
# Expected: 10.0.x or higher

---

Installation

Option 1: Install as NuGet Global Tool (recommended)

∏

dotnet tool install --global OracleMcp

Verify the installation:

oracle-mcp --help

To update to the latest version:

dotnet tool update --global OracleMcp

Option 2: Run from Source (development)

git clone https://github.com/4tech-sa/oracle-mcp.git
cd oracle-mcp
dotnet build

When running from source, use dotnet run --project src/OracleMcp instead of oracle-mcp in the configuration examples below.

---

Configuration by MCP Client

The server is configured through environment variables passed in the MCP client configuration. Choose the section that matches your client.

Claude Code (CLI)

Create or edit the file .claude.json in your project root directory:

{
  "mcpServers": {
    "oracle": {
      "command": "oracle-mcp",
      "env": {
        "ORACLE_HOST": "your_host",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "your_service_name",
        "ORACLE_USERNAME": "your_username",
        "ORACLE_PASSWORD": "your_password"
      }
    }
  }
}

Or configure globally (available in all projects) using the CLI:

claude mcp add -s user \
  -e ORACLE_HOST=your_host \
  -e ORACLE_PORT=1521 \
  -e ORACLE_SERVICE_NAME=your_service_name \
  -e ORACLE_USERNAME=your_username \
  -e ORACLE_PASSWORD=your_password \
  -e ORACLE_DEFAULT_SCHEMA=your_schema \
  -- oracle oracle-mcp

This saves the configuration to ~/.claude.json, making it available in all projects.

Claude Desktop

Open Settings > Developer > Edit Config and add:

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

{
  "mcpServers": {
    "oracle": {
      "command": "oracle-mcp",
      "env": {
        "ORACLE_HOST": "your_host",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "your_service_name",
        "ORACLE_USERNAME": "your_username",
        "ORACLE_PASSWORD": "your_password"
      }
    }
  }
}

After saving, restart Claude Desktop for the changes to take effect.

VS Code (GitHub Copilot)

Add to your .vscode/mcp.json in the project:

{
  "servers": {
    "oracle": {
      "command": "oracle-mcp",
      "env": {
        "ORACLE_HOST": "your_host",
        "ORACLE_PORT": "1521",
        "ORACLE_SERVICE_NAME": "your_service_name",
        "ORACLE_USERNAME": "your_username",
        "ORACLE_PASSWORD": "your_password"
      }
    }
  }
}

Running from Source

If you are running from source instead of the global tool, replace "command": "oracle-mcp" with:

{
  "command": "dotnet",
  "args": ["run", "--project", "/full/path/to/oracle-mcp/src/OracleMcp"]
}

---

Environment Variables

Variable	Required	Default	Description
ORACLE_HOST	Yes	—	Database hostname or IP
ORACLE_PORT	No	1521	Oracle listener port
ORACLE_SERVICE_NAME	Yes*	—	Oracle service name
ORACLE_SID	Yes*	—	Oracle SID (alternative to service name)
ORACLE_USERNAME	Yes	—	Database username
ORACLE_PASSWORD	Yes	—	Database password
ORACLE_QUERY_TIMEOUT	No	30	Query timeout in seconds (1–300)
ORACLE_MAX_ROWS	No	100	Maximum rows per query (1–1000)
ORACLE_DEFAULT_SCHEMA	No	USERNAME	Default schema for metadata tools
ORACLE_DICTIONARY_PATH	No	—	Path to the business dictionary directory

*Provide either ORACLE_SERVICE_NAME or ORACLE_SID, not both.

Connection Examples

Using service name (recommended):

"ORACLE_HOST": "dbhost.example.com",
"ORACLE_PORT": "1521",
"ORACLE_SERVICE_NAME": "ORCL.example.com"

Using SID:

"ORACLE_HOST": "dbhost.example.com",
"ORACLE_PORT": "1521",
"ORACLE_SID": "ORCL"

---

Verifying It Works

In Claude Code

After configuring, start Claude Code in the project directory and check if the MCP server loaded:

claude

Then ask:

search tables related to "employee"

If the server is connected correctly, you will see the AI querying Oracle and returning table results.

You can also check the MCP server status with:

/mcp

In Claude Desktop

After restarting, look for the tools icon (hammer) in the chat input. If Oracle MCP is loaded, you will see the 4 tools listed when you click it.

---

Usage Examples

Once configured, you can interact with your Oracle database naturally:

Discover tables:

"What tables are related to invoices?"

Understand structure:

"Describe the EMPLOYEES table"

Query data:

"Show me the top 10 employees by salary" "How many orders were placed this month?"

Use business dictionary:

"What does the STATUS column mean in the EMPLOYEES table?"

The AI will automatically use the right tools in sequence — searching for tables, describing their structure, and writing optimized queries.

---

Business Dictionary (Optional)

The business dictionary adds semantic context to table and column metadata. Create one JSON file per schema in the directory pointed to by ORACLE_DICTIONARY_PATH.

File naming: {SCHEMA_NAME}.json (e.g., HR.json, FINANCE.json)

{
  "$schema": "oracle-mcp-dictionary-v1",
  "version": "1.0.0",
  "schema": "HR",
  "author": "admin",
  "description": "HR system schema - employee and department management tables",
  "tables": {
    "EMPLOYEES": {
      "description": "Main employee records table",
      "columns": {
        "STATUS": {
          "description": "Employment status",
          "domain": {
            "A": "Active",
            "L": "On Leave",
            "T": "Terminated"
          }
        },
        "DEPARTMENT_ID": {
          "description": "Department assignment identifier"
        }
      }
    }
  }
}

The domain field maps coded values to human-readable descriptions, which is especially useful for status columns and category codes.

See dictionary/example/HR.json for a complete example.

---

Troubleshooting

"oracle-mcp" command not found

The .NET global tools directory may not be in your PATH.

# macOS / Linux
export PATH="$PATH:$HOME/.dotnet/tools"

# Add to your shell profile (~/.zshrc or ~/.bashrc) for persistence:
echo 'export PATH="$PATH:$HOME/.dotnet/tools"' >> ~/.zshrc

# Windows (PowerShell)
$env:PATH += ";$env:USERPROFILE\.dotnet\tools"

Connection timeout or refused

1. Verify the Oracle host is reachable: ping your_host
2. Verify the port is open: nc -zv your_host 1521 (macOS/Linux) or Test-NetConnection your_host -Port 1521 (PowerShell)
3. Check if you are using the correct SERVICE_NAME vs SID — ask your DBA if unsure
4. Ensure the database user has CREATE SESSION privilege at minimum

MCP server not appearing in Claude Desktop

1. Make sure you edited the correct config file (check paths above)
2. Restart Claude Desktop completely (quit and reopen, not just close the window)
3. Check Claude Desktop logs for errors:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\logs\mcp*.log

MCP server not working in Claude Code

1. Run /mcp in Claude Code to check server status
2. If the server shows as failed, check the error message
3. Try running the command directly in your terminal to see the error:

   ORACLE_HOST=your_host ORACLE_SERVICE_NAME=your_service oracle-mcp
   

4. Check if .claude.json is in the correct directory (project root)

ORA-12154: TNS could not resolve the connect identifier

The service name or SID is incorrect. Verify with your DBA or check tnsnames.ora if available.

ORA-01017: invalid username/password

Double-check ORACLE_USERNAME and ORACLE_PASSWORD. Oracle usernames are case-insensitive but passwords are case-sensitive.

Queries returning no results unexpectedly

• Check ORACLE_DEFAULT_SCHEMA — if not set, it defaults to the connected username
• The user may not have SELECT privileges on the target schema's tables
• Ask your DBA to grant: GRANT SELECT ON schema.table TO your_user

---

Development

# Build
dotnet build

# Run tests
dotnet test

# Run locally (for development)
dotnet run --project src/OracleMcp

License

MIT