What can you do with this server?

This MCP server enables LLMs like GitHub Copilot and Claude to securely query Oracle databases using read-only SQL operations through the Model Context Protocol. Core Capabilities: * Execute Read-Only SQL Queries - Run SELECT statements with configurable limits on maximum rows (default 1000) and query timeouts (default 30 seconds), receiving results with column names and execution metrics * Schema Introspection - List all accessible tables or retrieve detailed column information (names, types, metadata) for specific tables using get_database_schema * Security - Operates exclusively with dedicated read-only database users having only SELECT privileges, with resource limits to prevent exhaustion * Connection Management - Efficient Oracle connection pooling with configurable pool sizes for optimal performance * Audit Logging - Comprehensive logging of all queries with execution metrics in JSON format for monitoring and review * No Oracle Client Required - Uses Thin Mode with pure JavaScript driver, no Oracle Instant Client installation needed * stdio Transport - Communicates via standard I/O through MCP protocol without requiring an HTTP server Integration Options: * VS Code with GitHub Copilot for natural language database queries * Claude Desktop for direct AI assistant integration * Other MCP-compatible clients * Built-in test client for local verification Example Use Cases: Ask "What tables are in the database?" for schema exploration, "Show me the top 10 customers by revenue" for data analysis, or "How many active users do we have?" for reporting.

Which integrations are available for this server?

Enables GitHub Copilot to execute read-only SQL queries against Oracle databases, providing schema exploration and data retrieval capabilities through natural language prompts.

How do I use Oracle Database MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Oracle Database MCP Server show me the top 10 customers by total orders" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

Oracle Database MCP Server

by tannerpace

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

Oracle Database MCP Server

A Model Context Protocol (MCP) server that enables GitHub Copilot and other LLMs to execute read-only SQL queries against Oracle databases.

npm version License: AGPL v3 mcp-oracle-database MCP server

⚠️ Breaking Changes in v2.0

DATE, TIMESTAMP, TIMESTAMP WITH TIME ZONE, and TIMESTAMP WITH LOCAL TIME ZONE columns are now returned as formatted strings (YYYY-MM-DD HH:mm:ss) instead of raw JavaScript Date objects.

The timezone is controlled by ORACLE_TIMEZONE (IANA name). If unset it falls back to the server's system timezone, which may differ across machines.

Action required — add ORACLE_TIMEZONE to your .env or MCP env block:

ORACLE_TIMEZONE=UTC        # or e.g. America/Chicago

Related MCP server: MCP Server for Oracle Database

📦 Installation

From npm (quickest)

npm install -g mcp-oracle-database

Build from Source

git clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run build

macOS Apple Silicon (M1/M2/M3/M4) with no Oracle yet? See the macOS Setup Guide to spin up Oracle XE 21c locally via Colima.

🔌 Configure VS Code

Create .vscode/mcp.json in your workspace (or add to your global MCP config).

Option A — From Source

{
  "servers": {
    "oracleDatabase": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-oracle-database/dist/server.js"],
      "env": {
        "ORACLE_CONNECTION_STRING": "localhost:1521/XE",
        "ORACLE_USER": "system",
        "ORACLE_PASSWORD": "OraclePwd123",
        "ORACLE_TIMEZONE": "UTC",
        "ORACLE_POOL_MIN": "2",
        "ORACLE_POOL_MAX": "10",
        "QUERY_TIMEOUT_MS": "30000",
        "MAX_ROWS_PER_QUERY": "1000",
        "ENFORCE_READ_ONLY_QUERIES": "true",
        "MCP_MAX_RESPONSE_CHARS": "50000",
        "MCP_MAX_ROWS_IN_RESPONSE": "200",
        "MCP_MAX_STRING_LENGTH": "500"
      }
    }
  }
}

Replace /absolute/path/to/mcp-oracle-database with the real path on your machine (e.g. /Users/yourname/GITHUB/mcp-oracle-database).

Option B — From npm Global Install

{
  "servers": {
    "oracleDatabase": {
      "type": "stdio",
      "command": "mcp-database-server",
      "env": {
        "ORACLE_CONNECTION_STRING": "localhost:1521/XE",
        "ORACLE_USER": "your_user",
        "ORACLE_PASSWORD": "your_password",
        "ORACLE_TIMEZONE": "UTC",
        "ORACLE_POOL_MIN": "2",
        "ORACLE_POOL_MAX": "10",
        "QUERY_TIMEOUT_MS": "30000",
        "MAX_ROWS_PER_QUERY": "1000",
        "ENFORCE_READ_ONLY_QUERIES": "true",
        "MCP_MAX_RESPONSE_CHARS": "50000",
        "MCP_MAX_ROWS_IN_RESPONSE": "200",
        "MCP_MAX_STRING_LENGTH": "500"
      }
    }
  }
}

After saving, reload VS Code and open a Copilot chat in Agent mode. Try:

"What tables are in the database?"
"Describe the HELP table"
"Show me 5 rows from the HELP table"

Optional: Create a Read-Only User

Using SYSTEM is fine for local testing. For any real database, use a dedicated read-only user:

-- Connect: sqlplus system/OraclePwd123@localhost:1521/XEPDB1

CREATE USER readonly_user IDENTIFIED BY secure_password;
GRANT CREATE SESSION TO readonly_user;
GRANT SELECT ANY TABLE TO readonly_user;

-- Or restrict to specific tables:
-- GRANT SELECT ON myschema.orders TO readonly_user;
-- GRANT SELECT ON myschema.customers TO readonly_user;

Then update your .env or MCP config:

ORACLE_CONNECTION_STRING=localhost:1521/XEPDB1
ORACLE_USER=readonly_user
ORACLE_PASSWORD=secure_password

Features

🔒 Read-only access — Dedicated read-only database user for security
📡 stdio transport — No HTTP server; communicates via standard input/output
⚡ Connection pooling — Efficient Oracle connection management
📊 Schema introspection — Query table and column information
🔍 Advanced schema discovery — 5 specialized tools for tables, relationships, and data patterns
💾 In-memory caching — LRU cache with 5-minute TTL for fast repeated access
📝 Audit logging — All queries logged with execution metrics
⏱️ Timeout protection — Prevents long-running queries
🛡️ Result limits — Configurable row limits to prevent memory issues
🍎 No Oracle Client needed — Uses node-oracledb Thin Mode (pure JS, works on Apple Silicon)

Architecture

GitHub Copilot / LLM
        ↓ (MCP Protocol)
  MCP Client (spawns process)
        ↓ (JSON-RPC over stdio)
    MCP Server (Node.js)
        ↓ (node-oracledb Thin Mode)
  Oracle Database (read-only user)

Available Tools

Core Tools

`query_database`

Execute read-only SQL SELECT queries.

{
  "query": "SELECT table_name FROM user_tables FETCH FIRST 10 ROWS ONLY",
  "maxRows": 10
}

`get_database_schema`

Get a table list or column details for a specific table.

{ "tableName": "ORDERS" }

Schema Discovery Tools

Tool	Purpose	Cached
`listTables`	All accessible tables with metadata & optional row counts	✅
`describeTable`	Column types, constraints, primary/foreign keys	✅
`getTableRelations`	Foreign key relationships in JSON	✅
`getSampleValues`	Sample values to understand data formats	❌
`suggestRelatedTables`	Find related tables by FK, naming, shared columns	❌

📖 See Schema Discovery Documentation for full details and examples.

Example Copilot Prompts

"List all tables in the database"
"Describe the ORDERS table and its relationships"
"How many active users are there?"
"What are the top 5 products by sales this month?"
"Show me recent transactions for customer ID 12345"

Configuration Reference

All settings can go in .env or as env keys in your VS Code MCP config.

# Oracle Database Connection
ORACLE_CONNECTION_STRING=localhost:1521/XE    # host:port/service
ORACLE_USER=system
ORACLE_PASSWORD=OraclePwd123

# Timezone (REQUIRED for consistent date/timestamp output)
ORACLE_TIMEZONE=UTC                          # IANA timezone, e.g. America/New_York

# Connection Pool
ORACLE_POOL_MIN=2
ORACLE_POOL_MAX=10

# Query Safety
QUERY_TIMEOUT_MS=30000           # max query time in ms
MAX_ROWS_PER_QUERY=1000          # max rows Oracle will fetch
MAX_QUERY_LENGTH=50000           # max SQL length in chars
ENFORCE_READ_ONLY_QUERIES=true   # reject non-SELECT statements

# MCP Response Limits
MCP_MAX_RESPONSE_CHARS=50000     # hard cap on total response size
MCP_MAX_ROWS_IN_RESPONSE=200     # max rows per tool call response
MCP_MAX_STRING_LENGTH=500        # max chars per string field

# Logging
LOG_LEVEL=info
ENABLE_AUDIT_LOGGING=true
ENABLE_FILE_LOGGING=true
LOG_DIR=./logs
NODE_ENV=development

Large schemas: If your database has 500+ tables, raise MCP_MAX_RESPONSE_CHARS to 100000.

Development

Scripts

npm run build          # Compile TypeScript → dist/
npm run dev            # Watch mode compilation
npm run clean          # Remove dist/
npm run typecheck      # Type-check without compiling
npm start              # Start MCP server (requires build first)
npm run test-client    # Core tool tests against live Oracle DB
npm run test-discovery # Schema discovery tool tests

Project Structure

mcp-oracle-database/
├── src/
│   ├── server.ts               # MCP server entry point
│   ├── client.ts               # Core test client
│   ├── test-discovery.ts       # Discovery tools test client
│   ├── config.ts               # Zod-validated configuration
│   ├── database/
│   │   ├── oracleConnection.ts # Connection pool manager
│   │   ├── queryExecutor.ts    # Query execution + safety checks
│   │   └── types.ts
│   ├── tools/
│   │   ├── queryDatabase.ts    # query_database tool
│   │   ├── getSchema.ts        # get_database_schema tool
│   │   └── discovery/          # 5 schema discovery tools + cache
│   └── utils/
│       ├── logger.ts           # Lightweight file + console logger
│       └── responseFormatter.ts # MCP response size management
├── dist/                       # Compiled output (git-ignored)
├── .env                        # Your credentials (git-ignored)
├── .env.example                # Template
└── package.json

Security Considerations

Read-Only User — Database user should have only SELECT privileges in production
SQL Safety — The server trusts the LLM to generate valid SQL; the read-only user is the safety net
Query Limits — Row count and timeout limits prevent resource exhaustion
Audit Logging — All queries logged with timestamps for review
Local First — Designed to run on your machine; can still connect to remote databases

Troubleshooting

Connection failed

Error: ORA-12545: Connect failed because target host or object does not exist

Is Oracle running? docker ps | grep oracle-xe
Check the port: docker ps should show 0.0.0.0:1521->1521/tcp
Try localhost:1521/XE for SYSTEM, localhost:1521/XEPDB1 for other users

Wrong service name

Service	Use for
`localhost:1521/XE`	SYSTEM user, DBA operations
`localhost:1521/XEPDB1`	Regular application users

Permission denied

Error: ORA-00942: table or view does not exist

GRANT SELECT ANY TABLE TO your_user;

Response too large

Response for tool 'listTables' exceeded MCP_MAX_RESPONSE_CHARS

MCP_MAX_RESPONSE_CHARS=100000

Colima / Docker issues (macOS)

See macOS Setup Guide — Troubleshooting.

Thin Mode note

This project uses node-oracledb Thin Mode — a pure JavaScript driver that requires no Oracle Instant Client. It works on all platforms including Apple Silicon Macs.

Documentation

📚 Guides:

macOS Setup Guide — Local Oracle XE setup on Apple Silicon
Schema Discovery Guide — Advanced schema introspection tools
Schema Discovery Quick Reference — Cheat sheet for all discovery tools
Schema Discovery Examples — MCP message examples
VS Code Integration Guide — Set up with GitHub Copilot
Claude Desktop Integration Guide — Set up with Claude Desktop
MCP Integration Guide — MCP protocol deep dive
Architecture Overview — System architecture diagram
Logging Configuration — Logging setup and configuration

📝 Custom Instructions:

.github/copilot-instructions.md — Project-wide Copilot instructions
.github/instructions/ — Language-specific coding guidelines

Licensing

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

You are free to use, modify, and distribute this software under the terms of the AGPL-3.0. Any modified version deployed as a network service must make its source code available to users of that service.

See LICENSE.md for the full license text.

Oracle is a registered trademark of Oracle Corporation. This project is not affiliated with, endorsed by, or sponsored by Oracle Corporation.

Available Tools

2 tools

get_database_schemaA

Get database schema information. If tableName is provided, returns column details for that table. Otherwise, returns a list of all accessible tables.

ParametersJSON Schema

Name	Required	Description	Default
`tableName`	No	Optional table name to get column information for

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It describes the tool's conditional behavior based on the tableName parameter, which is useful context. However, it doesn't disclose important behavioral traits like whether this requires specific permissions, what 'accessible tables' means in terms of access control, error handling for invalid table names, or response format details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise with two sentences that efficiently convey all necessary information. The first sentence states the core purpose, and the second explains the conditional behavior. Every word earns its place with zero waste or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only schema inspection tool with no annotations and no output schema, the description provides adequate basic information about what the tool does and how parameters affect behavior. However, it lacks details about return format, error conditions, access restrictions, or what 'accessible tables' encompasses, which would be helpful given the absence of structured metadata.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the tableName parameter clearly documented as optional. The description adds value by explaining the semantic impact of providing vs. not providing this parameter: it changes the return type from column details to a table list. However, it doesn't add syntax or format details beyond what the schema provides, meeting the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and resource 'database schema information', with specific conditional behavior: returns column details for a specific table if tableName is provided, otherwise returns a list of all accessible tables. This distinguishes it from the sibling tool 'query_database', which presumably executes queries rather than retrieving schema metadata.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool: use with tableName parameter to get column details for that table, or without parameter to get a list of all tables. However, it doesn't explicitly state when NOT to use it or mention alternatives like the sibling 'query_database' tool, which could be relevant for schema exploration vs. data querying.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_databaseA

Execute a read-only SQL SELECT query against the Oracle database. Returns rows, column names, and execution metrics.

ParametersJSON Schema

Name	Required	Description
`query`	Yes	The SQL query to execute (SELECT statements only)
`maxRows`	No	Maximum number of rows to return (optional)
`timeout`	No	Query timeout in milliseconds (optional)

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively states the tool is 'read-only', which implies safety from mutations, and mentions return types and execution metrics, adding useful context. However, it lacks details on permissions, rate limits, error handling, or database-specific constraints, which are important for a database query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and concise, consisting of two sentences that efficiently convey the tool's purpose, constraints, and outputs without any wasted words. Every sentence earns its place by providing essential information, making it easy to understand at a glance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (database querying with multiple parameters) and the absence of annotations and output schema, the description does a good job by specifying the query type, database, and return data. However, it could be more complete by including details on output format, error responses, or connection requirements, which would help an agent use it more effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so the schema already documents all parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema, such as query syntax examples or default values for optional parameters. This meets the baseline score of 3, as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('Execute a read-only SQL SELECT query') and resources ('against the Oracle database'), and distinguishes it from potential siblings by specifying it's for SELECT queries only. It explicitly mentions what it returns ('rows, column names, and execution metrics'), making the purpose unambiguous and comprehensive.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool by specifying 'read-only SQL SELECT query' and 'SELECT statements only', which implicitly guides usage for data retrieval rather than modifications. However, it does not explicitly mention when not to use it or name alternatives like 'get_database_schema' for schema queries, leaving some room for improvement in sibling differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

2 tool updatesOct 25, 2025
- First observedget_database_schema
- First observedquery_database

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0

Disambiguation5/5

The two tools have clearly distinct purposes: get_database_schema retrieves metadata about the database structure, while query_database executes SQL queries for data retrieval. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tools follow a consistent verb_noun naming pattern (get_database_schema, query_database) with clear, descriptive names that align with their functions. The naming is uniform and predictable.

Tool Count2/5

With only 2 tools, the server feels under-scoped for an Oracle Database MCP Server, as it lacks essential operations like data manipulation (INSERT, UPDATE, DELETE), transaction management, or administrative tasks, making it incomplete for typical database workflows.

Completeness2/5

The tool surface is severely incomplete for a database server, covering only schema inspection and read-only queries. Missing are critical operations such as data modification, stored procedure execution, user management, and other core database functionalities, leading to significant gaps.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

QueryBearOAuth
io.github.spencerpauly
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Databases RAG Systems
2
mcpmyadminOAuth
ai.mcpmyadmin
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Databases Security
2
Dataassist-IOOAuth
io.github.DataAssistIO
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Search Databases
2
CloudQuellOAuth
com.cloudquell
Connects AI assistants to CloudQuell multi-cloud and AI cost, savings, anomaly, and budget data.
Cloud Platforms Monitoring Finance
1

Related MCP Servers

Oracle ADB MCP Server
Databases Cloud Platforms Developer Tools
hanley-development
F
license
Not graded
quality
D
maintenance
Connects to Oracle Autonomous Database via OCI Bastion tunneling to enable AI-powered database exploration. Supports schema introspection, automatic ERD generation, and read-only SQL query execution through natural language interfaces.
Updated 5 months ago (2026-04-05 01:40 UTC)
-
MCP Server for Oracle Database
Databases Developer Tools
kutsushitaneko
F
license
Not graded
quality
D
maintenance
Enables AI applications to run SQL queries and retrieve results from Oracle Database.
Updated a year ago (2025-05-11 15:35 UTC)
8
-
oradb-explorer-mcp
Databases Search
arun-siv
F
license
Not graded
quality
B
maintenance
Enables read-only exploration of Oracle databases through natural language, providing schema inspection and safe bounded SQL query execution.
Updated a month ago (2026-08-08 18:39 UTC)
-
MCP-Oracle
Databases Developer Tools
VasquezNodier
F
license
Not graded
quality
B
maintenance
Enables AI agents to connect to Oracle databases for schema exploration, PL/SQL source inspection, and read-only SQL queries, with optional write operations when explicitly enabled.
Updated 12 days ago (2026-08-25 19:27 UTC)
-

Appeared in Searches

Connecting Cursor to Oracle Database for Data Learning

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/tannerpace/mcp-oracle-database'

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

Oracle Database MCP Server

⚠️ Breaking Changes in v2.0

Table of Contents

📦 Installation

From npm (quickest)

Build from Source

🔌 Configure VS Code

Option A — From Source

Option B — From npm Global Install

Optional: Create a Read-Only User

Features

Architecture

Available Tools

Core Tools

query_database

get_database_schema

Schema Discovery Tools

Example Copilot Prompts

Configuration Reference

Development

Scripts

Project Structure

Security Considerations

Troubleshooting

Connection failed

Wrong service name

Permission denied

Response too large

Colima / Docker issues (macOS)

Thin Mode note

Documentation

Licensing

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Oracle ADB MCP Server

MCP Server for Oracle Database

oradb-explorer-mcp

MCP-Oracle

Appeared in Searches

Latest Blog Posts

MCP directory API

`query_database`

`get_database_schema`