Skip to main content
Glama

Oracle MCP Server

by smith-nathanh
GitHub
Python
MIT License
1
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Oracle MCP Server

Oracle Database MCP Server - Execute SQL queries, browse schemas, and analyze performance.

Table of Contents

Overview

This Model Context Protocol (MCP) server provides comprehensive Oracle Database interaction capabilities for AI assistants and development environments. Execute SQL queries safely, explore database schemas, analyze query performance, export data in multiple formats, and get intelligent database insights through any MCP-compatible client.

Features

  • Safe Query Execution - Execute SELECT queries with built-in safety controls
  • Schema Inspection - Browse database tables, views, procedures, and functions
  • Performance Analysis - Get execution plans and query performance metrics
  • Data Export - Export query results in JSON and CSV formats
  • Security Controls - Whitelist tables/columns and enforce read-only operations

Query Execution Capabilities

The MCP server provides rich query execution with automatic safety controls:

  • Automatic Row Limiting: SELECT queries are automatically limited to prevent resource exhaustion (configurable via QUERY_LIMIT_SIZE)
  • SQL Injection Prevention: Built-in keyword filtering blocks dangerous operations (DROP, DELETE, UPDATE, etc.)
  • Smart Query Enhancement: Queries without explicit ROWNUM/LIMIT clauses get automatic pagination
  • Data Type Handling: Automatic conversion of Oracle-specific types (LOB, DATE, NUMBER) to JSON-serializable formats
  • Execution Metrics: Every query returns execution time and row count statistics

Example Query Response:

{ "columns": ["EMPLOYEE_ID", "FIRST_NAME", "LAST_NAME", "SALARY"], "rows": [[100, "Steven", "King", 24000], [101, "Neena", "Kochhar", 17000]], "row_count": 2, "execution_time_seconds": 0.045, "query": "SELECT employee_id, first_name, last_name, salary FROM employees WHERE ROWNUM <= 100" }

Schema Inspection Capabilities

The server provides comprehensive database metadata that helps LLMs understand your database structure:

  • Table Discovery: Lists all accessible tables with row counts, last analysis dates, and comments
  • Column Details: Provides data types, nullable constraints, default values, and column comments
  • Relationship Insights: Views and their underlying table relationships
  • Stored Procedures: Available functions, procedures, and packages with their status

Example Table Metadata:

{ "owner": "HR", "table_name": "EMPLOYEES", "columns": [ { "column_name": "EMPLOYEE_ID", "data_type": "NUMBER", "nullable": "N", "column_comment": "Primary key of employees table" }, { "column_name": "FIRST_NAME", "data_type": "VARCHAR2", "data_length": 20, "nullable": "Y", "column_comment": "First name of the employee" } ], "table_comment": "Employees information including salary and department" }

Performance Analysis Features

  • Execution Plans: Generate and analyze query execution plans with cost estimates
  • Query Optimization: Identify table scans, index usage, and performance bottlenecks
  • Resource Estimates: Cost, cardinality, and byte estimates for query operations

GitHub Copilot Agent Interaction

Oracle MCP Server in GitHub Copilot

Example of the Oracle MCP Server responding to database queries through GitHub Copilot's agent model interface

When GitHub Copilot interacts with the MCP server, it receives structured data that enables sophisticated database assistance including query generation, schema understanding, and performance optimization recommendations.

Documentation

📚 Setup Guides:

🐳 New to Oracle? Start with the Docker Example to get running in minutes!

Quick Setup

Prerequisites

  • Python 3.10+
  • UV package manager
  • Oracle Database access
  • Oracle Instant Client (for advanced features)

Installation

  1. Clone and setup the project:
    git clone <repository-url> cd oracle-mcp-server ./setup.sh
  2. Configure database connection:
    cp .env.example .env # Edit .env with your Oracle database details
  3. Test the connection:
    uv run oracle-mcp-server --debug
    Alternative: Use the startup script for automatic environment setup:
    ./start_mcp_server.sh --debug
  4. Set up VS Code integration: See the VS Code Integration section below for detailed setup instructions.

Chat Demo (mcp-chat)

🤖 Want to see how an LLM uses MCP tools step-by-step?

The mcp-chat demo provides a demo on how an agent can connect to and query your Oracle database. This demo shows the raw tool usage patterns that LLMs follow when answering database questions using the MCP server.

Features

  • Direct Tool Usage: Watch the LLM call MCP tools in real-time
  • Step-by-Step Progress: See each tool call as it happens
  • Multiple Model Support: Works with any OpenRouter-compatible model
  • Configurable Timeouts: Control how long complex queries can run

Quick Start

# 1. Set up your OpenRouter API key export OPENROUTER_API_KEY="your-api-key-here" # 2. Set up database connection (use Docker example or your own) export DB_CONNECTION_STRING="testuser/TestUser123!@localhost:1521/testdb" # 3. Run a simple query uv run mcp-chat "What tables are in the database?" # 4. Run a more complex query with a specific model uv run mcp-chat --model openai/gpt-4.1 "Which department has the highest paid employee?"

Example: Multi-Turn Tool Usage

Here's what happens when you ask "Which department has the highest paid employee?" - notice how the LLM makes multiple tool calls to gather information before providing the answer:

$ uv run mcp-chat --model google/gemini-2.5-flash --timeout 120 "What department has the highest paid employee?" Using model: google/gemini-2.5-flash ╭────────────────────────────────── Welcome ───────────────────────────────────╮ │ Oracle Database Assistant │ │ I can help you explore and query your Oracle database. │ │ Type 'exit' to quit, 'clear' to start over. │ ╰──────────────────────────────────────────────────────────────────────────────╯ You: What department has the highest paid employee? Processing your request... Analyzing (iteration 1)... Using tools: list_tables Executing list_tables... Preview: { "tables": [ { "owner": "TESTUSER", "table_name": "DEPARTMENTS", "num_rows": 3, "last_analyzed": "2025-07-14T22:00:12", "table_comment": null, "tablespace_na... Analyzing (iteration 2)... Using tools: describe_table Executing describe_table... Preview: { "table_name": "EMPLOYEES", "owner": null, "columns": [ { "column_name": "ID", "data_type": "NUMBER", "data_length": 22, "data_precision": 10, "data_scale": 0,... Analyzing (iteration 3)... Using tools: describe_table Executing describe_table... Preview: { "table_name": "DEPARTMENTS", "owner": null, "columns": [ { "column_name": "ID", "data_type": "NUMBER", "data_length": 22, "data_precision": 10, "data_scale": ... Analyzing (iteration 4)... Using tools: execute_query Executing execute_query... Preview: { "columns": [ "DEPARTMENT_NAME" ], "rows": [ [ "Engineering" ] ], "row_count": 1, "execution_time_seconds": 0.002093, "query": "SELECT * FROM (SELECT d.name AS departm... Analyzing (iteration 5)... Ready to respond Preview: The department with the highest paid employee is Engineering. Processing complete Assistant: The department with the highest paid employee is Engineering.

Understanding the Tool Flow

In the example above, the LLM follows a logical progression:

  1. Discovery (list_tables): First explores what tables are available
  2. Schema Understanding (describe_table x2): Examines the structure of EMPLOYEES and DEPARTMENTS tables
  3. Query Execution (execute_query): Runs a SQL query
  4. Final Answer: Provides the specific result from the query data

This demonstrates how LLMs break down complex questions into discrete tool calls, gathering information step-by-step before synthesizing a final answer.

Command Options

# Use a specific model (default: openai/gpt-4.1) uv run mcp-chat --model openai/gpt-4.1 "your question" # Set custom timeout for complex queries (default: 60 seconds) uv run mcp-chat --timeout 120 "complex analysis question" # Enable debug logging uv run mcp-chat --debug "your question" # Interactive mode (no initial question) uv run mcp-chat # Get help uv run mcp-chat --help

Supported Models

The chat interface works with any OpenRouter-compatible model, but you'll want to use one that is adept at tool calling such as openai/gpt-4.1.

Tips for Best Results

  1. Be Specific: "Show me salaries by department" works better than "tell me about employees"
  2. Watch the Progress: The tool calls show you exactly how the LLM is thinking
  3. Adjust Timeouts: Complex analytical queries may need more time
  4. Try Different Models: Some models are better at following multi-step instructions

Docker Setup for Testing

🐳 New to Oracle? Get a complete test environment running in minutes!

We provide a ready-to-use Docker setup with Oracle Database XE and sample data. Perfect for:

  • Testing the MCP server
  • Learning Oracle database interactions
  • Development and prototyping

Quick Start

# 1. Start Oracle database with sample data cd docker-example docker-compose up -d # 2. Configure MCP server cp .env.docker ../.env # 3. Test the setup cd .. && uv run oracle-mcp-server --version

What You Get

  • Oracle Database XE 21c running in Docker
  • Sample database with employees and departments tables
  • Test user (testuser/TestUser123!) with appropriate permissions
  • Ready-to-use connection string for the MCP server

📖 Complete Docker Setup Guide →

The Docker example includes detailed instructions, troubleshooting, sample queries, and management commands.

VS Code Integration

Prerequisites

  1. Install VS Code extensions:

Setup Steps

  1. Complete the basic setup (see Quick Setup section above)
  2. Configure environment variables:
    • Ensure your .env file has the correct DB_CONNECTION_STRING
    • VS Code will automatically load environment variables from .env
  3. MCP Configuration: The project includes a pre-configured .vscode/mcp.json file:
    { "servers": { "oracle-mcp-server": { "command": "uv", "args": ["run", "python", "-m", "oracle_mcp_server.server"], "env": { "DB_CONNECTION_STRING": "${env:DB_CONNECTION_STRING}", "DEBUG": "${env:DEBUG}", "QUERY_LIMIT_SIZE": "${env:QUERY_LIMIT_SIZE}", "MAX_ROWS_EXPORT": "${env:MAX_ROWS_EXPORT}" } } } }
  4. Activate the MCP server:
    • Open this project folder in VS Code
    • Restart VS Code to load the MCP configuration
    • The Oracle MCP server will start automatically when GitHub Copilot needs it

Using the MCP Server

Once configured, you can interact with your Oracle database through GitHub Copilot:

  1. Ask database questions:
    • "Show me all tables in the database"
    • "Describe the EMPLOYEES table structure"
    • "What are the most recent orders?"
  2. Query assistance:
    • "Generate a query to find all customers from California"
    • "Explain this query's execution plan"
    • "Export the results as CSV"
  3. Schema exploration:
    • "What views are available?"
    • "Show me sample data from the PRODUCTS table"
    • "List all stored procedures"

Troubleshooting VS Code Integration

MCP server not starting:

  • Check VS Code's Output panel → "GitHub Copilot Chat" for error messages
  • Verify .env file exists and has correct DB_CONNECTION_STRING
  • Ensure uv is installed and available in PATH
  • Try restarting VS Code completely

Connection issues:

  • Test connection manually: uv run oracle-mcp-server --debug
  • Check Oracle database is accessible
  • Verify credentials in .env file

No database responses:

  • Ensure GitHub Copilot extension is activated
  • Check that .vscode/mcp.json exists in the workspace
  • Verify environment variables are loading (check VS Code terminal: echo $DB_CONNECTION_STRING)

Alternative: Using the Startup Script

For environments where the MCP server needs explicit environment setup, you can use the included startup script:

# Use the startup script instead of direct Python execution ./start_mcp_server.sh --version

The startup script automatically:

  • Activates the Python virtual environment
  • Loads environment variables from .env file
  • Verifies database connection string is available
  • Starts the MCP server with proper configuration

To use with VS Code MCP configuration, update .vscode/mcp.json:

{ "servers": { "oracle-mcp-server": { "command": "./start_mcp_server.sh", "args": [], "cwd": "${workspaceFolder}" } } }

This is particularly useful when:

  • Environment variables aren't loading automatically
  • Virtual environment isn't being detected
  • You need consistent startup behavior across different environments

Development with VS Code

The project includes VS Code-specific configurations:

  • Python interpreter: Automatically uses the UV virtual environment
  • File associations: SQL files are properly recognized
  • GitHub Copilot: Enabled for Python and SQL files
  • Debugging: Use F5 to debug the MCP server directly

Configuration

Environment Variables

VariableDescriptionDefaultExample
DB_CONNECTION_STRINGOracle connection stringRequiredoracle+oracledb://hr:password@localhost:1521/?service_name=XEPDB1
TABLE_WHITE_LISTComma-separated list of allowed tablesAll tablesEMPLOYEES,DEPARTMENTS
COLUMN_WHITE_LISTComma-separated list of allowed columnsAll columnsEMPLOYEES.ID,EMPLOYEES.NAME
QUERY_LIMIT_SIZEMaximum rows returned per query100500
MAX_ROWS_EXPORTMaximum rows for export operations1000050000
DEBUGEnable debug loggingFalseTrue

Connection String Examples

# Docker test database (from this project's setup) DB_CONNECTION_STRING="testuser/TestUser123!@localhost:1521/testdb" # Local Oracle XE (traditional format) DB_CONNECTION_STRING="oracle+oracledb://system:password@localhost:1521/?service_name=XE" # Oracle Cloud Autonomous Database DB_CONNECTION_STRING="oracle+oracledb://admin:password@hostname:1522/?service_name=your_service_tls&ssl_context=true" # Production with connection pooling DB_CONNECTION_STRING="oracle+oracledb://app_user:password@db.company.com:1521/?service_name=PROD&pool_size=10"

Note: The MCP server supports two connection string formats:

  • Simple format: username/password@host:port/service_name (recommended for Docker setup)
  • URL format: oracle+oracledb://username:password@host:port/?service_name=service_name (for compatibility)

Available Tools

When integrated with GitHub Copilot, the following tools are available:

  • execute_query - Execute SELECT, DESCRIBE, or EXPLAIN PLAN statements
  • describe_table - Get detailed table schema information
  • list_tables - Browse all database tables with metadata
  • list_views - Browse all database views
  • list_procedures - Browse stored procedures, functions, and packages
  • explain_query - Analyze query execution plans for performance tuning
  • generate_sample_queries - Generate example queries for table exploration
  • export_query_results - Export data in JSON or CSV format

Development

Running Tests

The project includes a comprehensive test suite with unit tests, integration tests, and utility tests.

# Run all tests uv run pytest # Run only unit tests (fast, no database required) uv run pytest -m unit # Run only integration tests (requires real database) uv run pytest -m integration # Run tests with coverage report uv run pytest --cov=src/oracle_mcp_server # Run specific test file uv run pytest tests/test_oracle_connection.py # Run tests with verbose output uv run pytest -v

Test Categories:

  • Unit Tests (-m unit): Fast tests using mocks, no database required
  • Integration Tests (-m integration): Tests against real Oracle database
  • Slow Tests (-m slow): Performance and stress tests

For Integration Tests: Integration tests require a real Oracle database. Set the TEST_DB_CONNECTION_STRING environment variable:

Using the Docker test database (recommended):

# Make sure Docker database is running cd docker-example && docker-compose up -d && cd .. # Set connection string and run integration tests export TEST_DB_CONNECTION_STRING="testuser/TestUser123!@localhost:1521/testdb" uv run pytest -m integration # Or run all tests including integration tests export TEST_DB_CONNECTION_STRING="testuser/TestUser123!@localhost:1521/testdb" uv run pytest

Using your own Oracle database:

export TEST_DB_CONNECTION_STRING="your_user/your_password@your_host:1521/your_service" uv run pytest -m integration

Code Formatting

uv run black src/ tests/ uv run isort src/ tests/

Type Checking

uv run mypy src/

Development Server

# Debug mode uv run oracle-mcp-server --debug # Use VS Code debugger with F5 or Ctrl+F5

Security Features

  • Read-only operations - Only SELECT, DESCRIBE, and EXPLAIN PLAN are allowed
  • SQL injection prevention - Basic keyword filtering and parameterized queries
  • Row limiting - Automatic ROWNUM restrictions to prevent resource exhaustion
  • Table/column whitelisting - Restrict access to specific database objects
  • Connection pooling - Efficient resource management

Troubleshooting

Common Issues

  1. Connection failures:
    • Verify Oracle database is running
    • Check connection string format
    • Ensure Oracle Instant Client is installed (if needed)
  2. Permission errors:
    • Verify database user has SELECT privileges
    • Check access to system views (ALL_TABLES, ALL_TAB_COLUMNS, etc.)
  3. MCP integration issues:
    • Restart VS Code after configuration changes
    • Check VS Code output panel for MCP server logs
    • Verify environment variables are loaded

Debug Mode

Run with debug logging to troubleshoot issues:

uv run oracle-mcp-server --debug

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Run tests and linting
  4. Submit a pull request

Support

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Execute SQL queries, browse schemas, and analyze Oracle Database performance through an AI-compatible Model Context Protocol server.

  1. Table of Contents
    1. Overview
      1. Features
      2. Query Execution Capabilities
      3. Schema Inspection Capabilities
      4. Performance Analysis Features
      5. GitHub Copilot Agent Interaction
    2. Documentation
      1. Quick Setup
        1. Prerequisites
        2. Installation
      2. Chat Demo (mcp-chat)
        1. Features
        2. Quick Start
        3. Example: Multi-Turn Tool Usage
        4. Understanding the Tool Flow
        5. Command Options
        6. Supported Models
        7. Tips for Best Results
      3. Docker Setup for Testing
        1. Quick Start
        2. What You Get
      4. VS Code Integration
        1. Prerequisites
        2. Setup Steps
        3. Using the MCP Server
        4. Troubleshooting VS Code Integration
        5. Alternative: Using the Startup Script
        6. Development with VS Code
      5. Configuration
        1. Environment Variables
        2. Connection String Examples
      6. Available Tools
        1. Development
          1. Running Tests
          2. Code Formatting
          3. Type Checking
          4. Development Server
        2. Security Features
          1. Troubleshooting
            1. Common Issues
            2. Debug Mode
          2. License
            1. Contributing
              1. Support

                Related MCP Servers

                • MSSQL MCP Server

                  JexinSam
                  -
                  security
                  A
                  license
                  -
                  quality
                  A Model Context Protocol server that enables secure and structured interaction with Microsoft SQL Server databases, allowing AI assistants to list tables, read data, and execute SQL queries with controlled access.
                  Last updated -
                  46
                  MIT License
                  • Linux
                  • Apple

                • OracleDB MCP Server

                  rahgadda
                  -
                  security
                  A
                  license
                  -
                  quality
                  A Model Context Protocol Server that enables LLMs to interact with Oracle Database by providing database tables/columns as context, allowing users to generate SQL statements and retrieve results using natural language prompts.
                  Last updated -
                  29
                  Apache 2.0

                • MCP Oracle Server

                  anpy-j
                  A
                  security
                  A
                  license
                  A
                  quality
                  A Model Context Protocol server that enables Claude to access and interact with Oracle databases through natural language queries.
                  Last updated -
                  3
                  MIT License

                • MCP SQL Server

                  ryudg
                  -
                  security
                  A
                  license
                  -
                  quality
                  A Model Context Protocol server that provides AI assistants with comprehensive access to SQL databases, enabling schema inspection, query execution, and database operations with enterprise-grade security.
                  Last updated -
                  6
                  2
                  MIT License

                View all related MCP servers

                Appeared in Searches

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/smith-nathanh/oracle-mcp-server'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server