GitHub Copilotやその他のLLMが、Oracleデータベースに対して読み取り専用のSQLクエリを実行できるようにするModel Context Protocol (MCP) サーバーです。
Related MCP server: MCP Server for Oracle Database
これはMacユーザーに推奨される手順です。DockerランタイムとしてColimaを使用し（Docker Desktopよりも軽量で、Apple Silicon上でネイティブに動作します）、ソースからMCPサーバーをビルドします。
Homebrew（インストール済みの場合はスキップ）:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"Node.js v18+（nvm経由を推奨）:
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Reload your shell config, then install Node
source ~/.zshrc
nvm install 20
nvm use 20
node --version # should print v20.x.xまたはHomebrew経由:
brew install node
node --versionColima + Docker CLI:
brew install colima dockerColimaはmacOS用の軽量コンテナランタイムです。Docker Desktopは不要です。
# Start with enough resources for Oracle XE (needs at least 2GB RAM)
colima start --cpu 2 --memory 4 --disk 30
# Verify Docker is working
docker psすでに少ないメモリでColimaを実行している場合は、
colima stopを実行してから、上記のフラグで再起動してください。
Oracleのコンテナレジストリからイメージをプルするには、無料アカウントが必要です。
https://container-registry.oracle.com で無料アカウントを作成します。
ログインし、Database → express に移動して、Accept License Agreementをクリックします。
ターミナルからログインします:
docker login container-registry.oracle.com
# Enter your Oracle account email and password when promptedOracle XE 21cをプルして実行します:
docker run -d \
--name oracle-xe \
-p 1521:1521 \
-p 5500:5500 \
-e ORACLE_PWD=OraclePwd123 \
container-registry.oracle.com/database/express:latest準備ができるまで待ちます（初回起動時は60〜90秒かかります）:
# Poll health status — wait for "healthy"
watch -n 5 'docker inspect --format="{{.State.Health.Status}}" oracle-xe'
# Or tail the logs directly
docker logs -f oracle-xe
# Look for: DATABASE IS READY TO USE!データベースは以下で利用可能です:
接続文字列: localhost:1521/XE
SYSTEMパスワード: OraclePwd123
Web UI (EM Express): http://localhost:5500/em
サービス名の注意: Oracle XE 21cには2つのサービス名があります:
XE— コンテナデータベース (CDB)、SYSTEMユーザーで使用
XEPDB1— プラガブルデータベース (PDB)、通常のアプリケーションユーザーで使用
後でデータベースを起動・停止するには:
docker start oracle-xe
docker stop oracle-xegit clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run buildcp .env.example .envローカルのOracle XE用に.envを編集します（試用におすすめ）:
ORACLE_CONNECTION_STRING=localhost:1521/XE
ORACLE_USER=system
ORACLE_PASSWORD=OraclePwd123本番環境で使用する場合は、まず専用の読み取り専用ユーザーを作成してください。読み取り専用ユーザーの作成を参照してください。
# Core tests: connects to Oracle, queries schema and version
npm run test-client
# Schema discovery tool tests
npm run test-discovery期待される出力:
✅ All tests completed successfully!
📊 Test Summary:
1. List Tools: ✅
2. List Tables (fast): ✅
3. List Tables (with counts): ✅
4. Describe Table: ✅
5. Get Table Relations: ✅
6. Get Sample Values: ✅
7. Suggest Related Tables: ✅
8. Cache Test: ✅以下のVS Codeの設定を参照してください。
最新のコードを取得でき、Copilotに接続する前にテストスイートを実行してすべてが正常に動作することを確認できます。
git clone https://github.com/tannerpace/mcp-oracle-database.git
cd mcp-oracle-database
npm install
npm run buildソースをクローンせずにサーバーバイナリのみが必要な場合:
npm install -g mcp-oracle-databaseVS Codeワークスペースに.vscode/mcp.jsonを作成します（またはグローバルMCP設定に追加します）:
{
"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_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"
}
}
}
}/absolute/path/to/mcp-oracle-databaseを、マシン上の実際のパス（例: /Users/yourname/GITHUB/mcp-oracle-database）に置き換えてください。
{
"servers": {
"oracleDatabase": {
"type": "stdio",
"command": "mcp-database-server",
"env": {
"ORACLE_CONNECTION_STRING": "localhost:1521/XE",
"ORACLE_USER": "your_user",
"ORACLE_PASSWORD": "your_password",
"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"
}
}
}
}設定を保存した後、VS Codeをリロードし、エージェントモードでCopilotチャットを開きます。以下を試してください:
"What tables are in the database?"
"Describe the HELP table"
"Show me 5 rows from the HELP table"ローカルテストではSYSTEMを使用しても問題ありませんが、実際のデータベースでは専用の読み取り専用ユーザーを作成してください。
Oracleに接続します（sqlplusやDBeaverなどのGUIを使用）:
-- For Oracle XE local Docker, connect with:
-- 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;次に、.envまたはMCP設定を更新します:
ORACLE_CONNECTION_STRING=localhost:1521/XEPDB1
ORACLE_USER=readonly_user
ORACLE_PASSWORD=secure_password🔒 読み取り専用アクセス — セキュリティのため、専用の読み取り専用データベースユーザーを使用
📡 stdioトランスポート — 標準入出力経由で通信（HTTPサーバーは不要）
⚡ 接続プーリング — 効率的なOracle接続管理
📊 スキーマイントロスペクション — テーブルおよび列情報のクエリ
🔍 高度なスキーマ探索 — テーブル、リレーションシップ、データパターンを探索するための5つの専門ツール
💾 インメモリキャッシュ — LRUキャッシュによる高速な繰り返しアクセス（TTL 5分）
📝 監査ログ — 実行メトリクスを含むすべてのクエリをログ記録
⏱️ タイムアウト保護 — 長時間実行されるクエリを防止
🛡️ 結果制限 — メモリ問題を防止するための設定可能な行制限
🍎 Oracle Client不要 — node-oracledb Thin Modeを使用（純粋なJS、Apple Siliconで動作）
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)query_database読み取り専用のSQL SELECTクエリを実行します。
{
"query": "SELECT table_name FROM user_tables FETCH FIRST 10 ROWS ONLY",
"maxRows": 10
}get_database_schemaテーブルリストまたは特定のテーブルの列詳細を取得します。
{ "tableName": "ORDERS" }包括的なスキーマイントロスペクションのための5つの専門ツール:
ツール | 目的 | キャッシュ |
| メタデータとオプションの行数を含むすべてのアクセス可能なテーブル | ✅ |
| 列の型、制約、主キー/外部キー | ✅ |
| JSON形式の外部キーリレーションシップ | ✅ |
| データ形式を理解するためのサンプル値 | ❌ |
| FK、命名、共有列による関連テーブルの検索 | ❌ |
📖 詳細と例については、スキーマ探索ドキュメントを参照してください。
"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"すべての設定は、.envまたはVS Code MCP設定のenvキーに記述できます。
# Oracle Database Connection
ORACLE_CONNECTION_STRING=localhost:1521/XE # host:port/service
ORACLE_USER=system
ORACLE_PASSWORD=OraclePwd123
# 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大規模なスキーマ: データベースに500以上のテーブルがある場合は、
MCP_MAX_RESPONSE_CHARSを100000に増やしてください。
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 testsmcp-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読み取り専用ユーザー — 本番環境では、データベースユーザーはSELECT権限のみを持つべきです。
インジェクション保護なし — サーバーはLLMが有効なSQLを生成することを信頼します。読み取り専用ユーザーが安全策となります。
クエリ制限 — 行数とタイムアウトの制限により、リソースの枯渇を防ぎます。
監査ログ — すべてのクエリがタイムスタンプ付きでログ記録され、レビュー可能です。
ローカル使用 — このサーバーはマシン上で直接実行するように設計されています。ローカルで実行しながら、リモートデータベースにアクセスすることも可能です。
colima status
colima start --cpu 2 --memory 4 # Oracle needs at least 2GB RAM
docker ps # verify Docker is available# Check if container exists
docker ps -a | grep oracle-xe
# View startup logs
docker logs oracle-xe
# Already exists but stopped — just start it
docker start oracle-xe
# Check health status
docker inspect --format='{{.State.Health.Status}}' oracle-xe
# Wait for: healthyError: ORA-12545: Connect failed because target host or object does not existOracleは実行中ですか？ docker ps | grep oracle-xe
ポートがマッピングされているか確認: docker psで0.0.0.0:1521->1521/tcpが表示されるはずです。
SYSTEMユーザーにはlocalhost:1521/XE、その他のユーザーにはlocalhost:1521/XEPDB1を試してください。
サービス | 用途 |
| SYSTEMユーザー、DBA操作 |
| 通常のアプリケーションユーザー |
Error: ORA-00942: table or view does not existユーザーにSELECT権限を付与します:
GRANT SELECT ANY TABLE TO your_user;Error: unauthorized: authentication requiredhttps://container-registry.oracle.com で無料アカウントを作成します。
Database → express のライセンスに同意します。
docker login container-registry.oracle.comを実行します。
Response for tool 'listTables' exceeded MCP_MAX_RESPONSE_CHARS.envまたはVS Code MCP設定で制限を増やします:
MCP_MAX_RESPONSE_CHARS=100000このプロジェクトはnode-oracledb Thin Modeを使用しています。これはOracle Instant Clientを必要としない純粋なJavaScriptドライバです。Apple Silicon Macを含むすべてのプラットフォームで動作します。
📚 統合ガイド:
スキーマ探索ガイド — 高度なスキーマイントロスペクションツール
スキーマ探索クイックリファレンス — すべての探索ツールのチートシート
スキーマ探索の例 — MCPメッセージの例
VS Code統合ガイド — GitHub Copilotとのセットアップ
Claude Desktop統合ガイド — Claude Desktopとのセットアップ
MCP統合ガイド — MCPプロトコルの詳細解説
アーキテクチャ概要 — システムアーキテクチャ図
ログ設定 — ログのセットアップと設定
📝 カスタム指示:
.github/copilot-instructions.md — プロジェクト全体のCopilot指示
.github/instructions/ — 言語固有のコーディングガイドライン
OracleはOracle Corporationの登録商標です。 このプロジェクトはOracle Corporationと提携、承認、または後援を受けていません。
このプロジェクトはGNU General Public License v3.0 (GPLv3) の下で利用可能です。
GPLv3を選択した場合、追加の利用分野制限なしで、記述通りのGPLv3の権利を受け取ります。ライセンス全文についてはLICENSEを、ライセンスの概要についてはLICENSE.mdを参照してください。
交渉による商用条件、保証の確約、または独自の配布権など、代替条件を希望する当事者向けに、作成者から個別の商用ライセンスが提供される場合があります。
📄 ライセンスの概要についてはLICENSE.mdを参照してください。
📄 個別の商用/政府機関向けライセンス条件についてはCOMMERCIAL_LICENSE.mdを参照してください。
貢献を歓迎します！Issueまたはプルリクエストを作成してください。
Get database schema information. If tableName is provided, returns column details for that table. Otherwise, returns a list of all accessible tables.
| Name | Required | Description | Default |
|---|---|---|---|
| tableName | No | Optional table name to get column information for |
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.
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.
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.
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.
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.
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.
Execute a read-only SQL SELECT query against the Oracle database. Returns rows, column names, and execution metrics.
| Name | Required | Description | Default |
|---|---|---|---|
| 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) |
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.
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.
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.
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.
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.
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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_database_schemaquery_databaseScored across 2 tools
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.
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.
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.
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.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Query Postgres, MySQL, SQL Server, Oracle, BigQuery, ClickHouse and Redshift from your AI client.
