Oracle

You can use the Oracle MCP Server to safely run SQL queries against an Oracle database, inspect schemas, and analyze performance from any MCP-compatible client. It enforces read-only access, protects against unsafe operations, and returns query metrics and exportable results to help you build intelligent database tools and assistants.

How to use

Connect your MCP client and establish a database connection using a valid connection string. You can safely execute SELECT queries, inspect schemas, and request execution plans or performance metrics. Use whitelisting options to restrict access to specific tables or columns. When you run queries, you receive structured results including columns, rows, row counts, and execution time. You can export results in JSON or CSV formats for reporting or downstream processing.

How to install

Prerequisites are required to run the MCP server and interact with your Oracle database.

# 1. Install prerequisites
# Ensure Python 3.10+ is available on your system

# 2. Install or verify UV package manager is available
# (This project uses the UV workflow for running the MCP server)

# 3. Set up the project locally
# If you are integrating via the VS Code workflow, you may follow the local setup steps described below.

Step-by-step commands to initialize and run the MCP server from a local environment (Python-based) are shown here. Follow these exact commands to start the server and verify connectivity.

# 1. Install dependencies and prepare environment (example commands)
# These commands assume you are in the project root

pip install -r requirements.txt

# 2. Configure database connection (example)
cp .env.example .env
# Edit .env to include your Oracle DB details

# 3. Start the MCP server in debug mode to verify setup
uv run oracle-mcp-server --debug

Configuration and usage notes

Configure environment variables to control access and behavior. Key options include the database connection string, read/write whitelists, query limits, and debugging. For example, you can set a maximum number of rows returned per query and enable debugging logs during setup.

# Example environment variable setup
export DB_CONNECTION_STRING="oracle+oracledb://user:password@host:port/?service_name=SERVICE"
export TABLE_WHITE_LIST="EMPLOYEES,DEPARTMENTS"
export COLUMN_WHITE_LIST="EMPLOYEES.ID,EMPLOYEES.NAME"
export QUERY_LIMIT_SIZE=100
export MAX_ROWS_EXPORT=50000
export DEBUG=True

Security and behavior notes

The MCP server provides read-only operations by default and enforces SQL injection safeguards. It automatically limits result sets to prevent resource exhaustion and supports safe descriptive actions like DESCRIBE and EXPLAIN PLAN. You can rely on accurate data typing conversion for JSON-compatible output.

Troubleshooting

If you encounter connection or runtime issues, verify that the Oracle database is reachable, the connection string is correct, and necessary Oracle client components are installed. Check that the MCP server process is running and that environment variables are loaded in your shell or IDE. For debugging, run with the --debug flag and inspect the log output.

Notes on VS Code integration

When integrating with a code editor or an agent like GitHub Copilot, ensure the MCP server is started and reachable by the editor. The integration loads environment variables from your configured .env file and uses a predefined startup command to start the server when needed.

Available tools and actions overview

The MCP server exposes tools to execute queries, inspect tables, explore schemas, and export data. You can run queries, describe tables, list tables and views, explore procedures, analyze execution plans, generate sample queries, and export results in JSON or CSV.

Available tools

execute_query

Execute SELECT, DESCRIBE, or EXPLAIN statements with safety controls and automatic pagination when needed.

describe_table

Return detailed schema information for a table, including columns and data types.

list_tables

List all accessible tables with metadata such as row counts and comments.

list_views

List all accessible database views with basic metadata.

list_procedures

List stored procedures, functions, and packages available in the schema.

explain_query

Analyze a query's execution plan and performance characteristics.

generate_sample_queries

Provide example queries suitable for exploring a given table or schema.

export_query_results

Export results to JSON or CSV format for external use.