Provides a ready-to-use Docker setup with Oracle Database XE and sample data for testing and development environments
Uses .ENV files for configuration management, allowing easy setup of database connections and security parameters
Enables GitHub Copilot to execute SQL queries, browse database schemas, analyze performance, and provide intelligent database insights through structured Oracle database interactions
Includes a comprehensive test suite with unit tests, integration tests, and utility tests for development and testing
Built with Python and provides comprehensive Oracle database interaction capabilities including executing queries, exploring schemas, and analyzing performance
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:
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:
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
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:
Docker Example Setup - Complete Oracle database in Docker with sample data
Complete Setup Guide - Step-by-step instructions for any Oracle database
Quick Reference - Credentials, commands, and troubleshooting
🐳 New to Oracle? Start with the Docker Example to get running in minutes!
Quick Setup
Prerequisites
Python 3.10+
Oracle Database access
Oracle Instant Client (for advanced features)
Installation
Clone and setup the project:
git clone <repository-url> cd oracle-mcp-server ./setup.shConfigure database connection:
cp .env.example .env # Edit .env with your Oracle database detailsTest the connection:
uv run oracle-mcp-server --debugAlternative: Use the startup script for automatic environment setup:
./start_mcp_server.sh --debugSet 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
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:
Understanding the Tool Flow
In the example above, the LLM follows a logical progression:
Discovery (
list_tables
): First explores what tables are availableSchema Understanding (
describe_table
x2): Examines the structure of EMPLOYEES and DEPARTMENTS tablesQuery Execution (
execute_query
): Runs a SQL queryFinal 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
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
Be Specific: "Show me salaries by department" works better than "tell me about employees"
Watch the Progress: The tool calls show you exactly how the LLM is thinking
Adjust Timeouts: Complex analytical queries may need more time
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
What You Get
Oracle Database XE 21c running in Docker
Sample database with employees and departments tables
Test user (
testuser/TestUser123!
) with appropriate permissionsReady-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
Install VS Code extensions:
GitHub Copilot - Required for MCP integration
Python - Recommended for development
Setup Steps
Complete the basic setup (see Quick Setup section above)
Configure environment variables:
Ensure your
.env
file has the correctDB_CONNECTION_STRING
VS Code will automatically load environment variables from
.env
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}" } } } }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:
Ask database questions:
"Show me all tables in the database"
"Describe the EMPLOYEES table structure"
"What are the most recent orders?"
Query assistance:
"Generate a query to find all customers from California"
"Explain this query's execution plan"
"Export the results as CSV"
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 correctDB_CONNECTION_STRING
Ensure
uv
is installed and available in PATHTry 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 workspaceVerify 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:
The startup script automatically:
Activates the Python virtual environment
Loads environment variables from
.env
fileVerifies database connection string is available
Starts the MCP server with proper configuration
To use with VS Code MCP configuration, update
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
Variable | Description | Default | Example |
| Oracle connection string | Required |
|
| Comma-separated list of allowed tables | All tables |
|
| Comma-separated list of allowed columns | All columns |
|
| Maximum rows returned per query |
|
|
| Maximum rows for export operations |
|
|
| Enable debug logging |
|
|
Connection String Examples
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 statementsdescribe_table
- Get detailed table schema informationlist_tables
- Browse all database tables with metadatalist_views
- Browse all database viewslist_procedures
- Browse stored procedures, functions, and packagesexplain_query
- Analyze query execution plans for performance tuninggenerate_sample_queries
- Generate example queries for table explorationexport_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.
Test Categories:
Unit Tests (
-m unit
): Fast tests using mocks, no database requiredIntegration Tests (
-m integration
): Tests against real Oracle databaseSlow 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):
Using your own Oracle database:
Code Formatting
Type Checking
Development Server
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
Connection failures:
Verify Oracle database is running
Check connection string format
Ensure Oracle Instant Client is installed (if needed)
Permission errors:
Verify database user has SELECT privileges
Check access to system views (ALL_TABLES, ALL_TAB_COLUMNS, etc.)
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:
License
MIT License - see LICENSE file for details.
Contributing
Fork the repository
Create a feature branch
Run tests and linting
Submit a pull request
Support
Check the Issues page
Review the Docker Example for sample queries
See Complete Setup Guide for configuration examples
This server cannot be installed
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.
Related MCP Servers
- -securityAlicense-qualityA 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 -48MIT License
- -securityAlicense-qualityA 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 -29Apache 2.0
- AsecurityAlicenseAqualityA Model Context Protocol server that enables Claude to access and interact with Oracle databases through natural language queries.Last updated -3MIT License
- -securityAlicense-qualityA 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 -12MIT License