GitHub Copilot 및 기타 LLM이 Oracle 데이터베이스에 대해 읽기 전용 SQL 쿼리를 실행할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.
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로 이동하여 라이선스 계약 수락을 클릭합니다.
터미널에서 로그인합니다:
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
웹 UI (EM Express): http://localhost:5500/em
서비스 이름 참고: Oracle XE 21c에는 두 가지 서비스 이름이 있습니다:
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 캐시를 통한 빠른 반복 액세스 (5분 TTL)
📝 감사 로깅 — 실행 지표와 함께 모든 쿼리 기록
⏱️ 시간 초과 보호 — 장기 실행 쿼리 방지
🛡️ 결과 제한 — 메모리 문제 방지를 위한 구성 가능한 행 제한
🍎 Oracle 클라이언트 불필요 — node-oracledb Thin 모드 사용 (순수 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이 프로젝트는 Oracle Instant Client가 필요 없는 순수 JavaScript 드라이버인 node-oracledb Thin 모드를 사용합니다. 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를 참조하세요.
기여를 환영합니다! 이슈를 열거나 풀 리퀘스트를 보내주세요.
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.
