Oracle ERP MCP Server
This server lets AI assistants safely explore and report on an Oracle ERP database in read-only mode.
Discover the schema —
list_tableslists tables/views with business descriptions (optionally filtered by name substring), anddescribe_tableshows columns, types, comments, primary keys and foreign keys for a given table or view.Ask ad-hoc business questions in SQL —
run_queryexecutes a single guarded OracleSELECT/WITHstatement and returns JSON rows, with an optionalmax_rowslimit (hard cap 200). DML/DDL, PL/SQL, DB links andDBMS_*/UTL_*packages are rejected.Run curated reports —
list_reportsshows pre-approved PL/SQL reports (returningSYS_REFCURSOR) and their parameters;run_reportexecutes one by name with validatedstring/number/dateparameters such as supplier performance, waste paper quality, stock balance, production scrap and monthly purchases.Stay safe by design — every tool is read-only, non-destructive, idempotent and closed-world, so no ERP data can be modified.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Oracle ERP MCP Server Show me the scrap rate per corrugator and tell me which product is the worst."
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.
Oracle ERP MCP Server
A secure, read-only Model Context Protocol server that lets AI assistants (Claude, GitHub Copilot, Cursor, …) explore and report on Oracle-based ERP databases. Users can ask their ERP data business questions in plain language. They don't need to write SQL or file a ticket for a new report.
"Which waste paper supplier caused the highest moisture deductions last quarter?" "Show me the scrap rate per corrugator and tell me which product is the worst." "What is the current stock value of raw materials in warehouse W01?"
The project ships with a dockerised Oracle Database 23ai Free instance pre-loaded with a realistic ERP schema for a paper & corrugated packaging manufacturer: purchasing, weighbridge (truck scale) tickets, inventory, production work orders, and a curated PL/SQL report package.
Features
5 MCP tools: schema discovery, table description, guarded ad-hoc SQL, curated reports.
Defence-in-depth security: a least-privilege DB user,
READ ONLYtransactions and a SQL guard (see Security model).Curated reports: expose existing PL/SQL procedures that return a
SYS_REFCURSOR. You add them through a JSON file, with no code changes.LLM-friendly metadata: table and column comments, primary keys and foreign keys help the model write correct joins.
Safe output: row limits with truncation flags, query timeouts, and dates formatted without timezone shifts. LOB and BLOB values are handled safely.
Audit log: every tool call is logged as JSON to
stderr(tool, SQL, row count, duration, error).No Oracle Client needed: uses
node-oracledbin Thin mode.Tested: unit tests with an in-memory MCP client, plus integration tests against a real Oracle database in CI.
Related MCP server: mcp-oraclefusion
Architecture
flowchart LR
subgraph Client["AI client"]
LLM["Claude / Copilot / Cursor"]
end
subgraph Server["oracle-erp-mcp (Node.js)"]
Tools["MCP tools"]
Guard["SQL guard"]
Reports["Report registry<br/>config/reports.json"]
Audit["Audit log (stderr)"]
end
subgraph DB["Oracle Database"]
Reader["MCP_READER<br/>(READ grants only)"]
Schema["ERP_DEMO schema"]
Pkg["ERP_REPORTS package<br/>(SYS_REFCURSOR)"]
end
LLM -- "stdio / JSON-RPC" --> Tools
Tools --> Guard --> Reader
Tools --> Reports --> Pkg
Tools --> Audit
Reader --> Schema
Pkg --> SchemaTools
Tool | Description |
| Tables and views in the configured schema, with business descriptions and approx. row counts. |
| Columns, types, nullability, comments, primary key and foreign keys. |
| Executes a single guarded |
| Lists curated reports and their parameters. |
| Runs a curated report (PL/SQL procedure returning |
All tools declare explicit MCP tool hints: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false.
Security model
An LLM must never be able to change ERP data, so the server applies several independent layers:
# | Layer | What it does |
1 | Least-privilege user |
|
2 | Read-only transaction | Every call runs inside |
3 | SQL guard | Single statement only; must start with |
4 | Curated report registry | Only procedures listed in |
5 | Resource limits | Row limit ( |
6 | Audit trail | JSON log line per tool call on |
The integration tests bypass the SQL guard on purpose. They check that the database itself still rejects DELETE, SELECT … FOR UPDATE and DDL.
Layer 1 is the real security boundary. In production, always connect with a dedicated read-only user, and preferably against a reporting replica or standby.
Quick start
Prerequisites: Node.js ≥ 18, Docker.
git clone https://github.com/GokhanHepyetiker/oracle-erp-mcp.git
cd oracle-erp-mcp
npm install
# 1. Start Oracle 23ai Free with the demo ERP schema (first start takes a few minutes)
npm run db:up
# 2. Build the server
npm run build
# 3. Try it in the MCP Inspector
# (set the variables from .env.example in your shell first)
npm run inspectorUse it from VS Code (GitHub Copilot)
This repository already contains .vscode/mcp.json for the demo database. Open the folder in VS Code, run npm run build, and then start the oracle-erp server from the MCP view. Its tools then become available in Copilot Chat (Agent mode).
Use it from Claude Desktop
Add the server to claude_desktop_config.json:
{
"mcpServers": {
"oracle-erp": {
"command": "node",
"args": ["/absolute/path/to/oracle-erp-mcp/dist/index.js"],
"env": {
"ORACLE_USER": "mcp_reader",
"ORACLE_PASSWORD": "McpReader#2026",
"ORACLE_CONNECT_STRING": "localhost:1521/FREEPDB1",
"ORACLE_SCHEMA": "ERP_DEMO"
}
}
}
}Configuration
Variable | Required | Default | Description |
| yes | Read-only database user. | |
| yes | Password of that user. | |
| yes | Easy Connect string, e.g. | |
| yes | Schema exposed to the assistant (e.g. your ERP schema). | |
| no |
| Default and maximum rows returned per call (max |
| no |
| Round-trip timeout per database call. |
| no |
| Path to the curated report registry. |
Adding your own reports
Any PL/SQL procedure whose last parameter is an OUT SYS_REFCURSOR can be exposed:
PROCEDURE open_orders (p_supplier_code IN VARCHAR2, p_result OUT SYS_REFCURSOR);{
"name": "open_orders",
"title": "Open purchase orders",
"description": "Purchase orders that are not fully received yet.",
"procedure": "ERP.PURCHASING_REPORTS.OPEN_ORDERS",
"parameters": [
{ "name": "supplier_code", "type": "string", "description": "Optional supplier filter" }
]
}Supported parameter types are string, number and date (passed as YYYY-MM-DD). Grant EXECUTE on the package to the read-only user.
Demo data model
Table | Content |
| 15 domestic and import vendors (waste paper, pulp, chemicals, spare parts). |
| Raw materials, chemicals, paper reels (testliner/fluting/kraftliner), corrugated boxes, spares. |
| Raw material yard, reel store, finished goods (2 sites), chemicals & spares. |
| 420 orders in TRY / EUR / USD with realistic statuses. |
| Lines with buyer-specific discount behaviour and received quantities. |
| 900 truck-scale tickets with moisture/contamination deductions ( |
| 320 paper machine (PM1/PM2) and corrugator (CORR1/CORR2) orders with scrap. |
| ~3,000 receipts, production issues and receipts, and shipments. |
The data is generated deterministically (seeded DBMS_RANDOM) and contains patterns for the assistant to discover. For example, some suppliers deliver systematically wetter or more contaminated loads, and one corrugator produces more scrap than the other.
Curated reports in ERP_DEMO.ERP_REPORTS: supplier_performance, waste_paper_quality, stock_balance, production_scrap, monthly_purchases.
Example questions
"List the tables and explain the data model in two sentences."
"Using the waste paper quality report, which suppliers should we talk to about moisture?"
"Compare the average discount each buyer achieved in 2026."
"Which finished goods have the highest stock value in the Ankara hub?"
"Show monthly TRY purchase spend for 2025 and describe the trend."
Development
npm run typecheck # TypeScript strict mode
npm test # unit tests (no database needed)
npm run test:integration # requires `npm run db:up`
npm run dev # run from source with tsx
npm run db:down # stop and remove the demo databasesrc/
index.ts entry point (stdio transport, graceful shutdown)
server.ts MCP tool definitions and audit logging
db.ts Oracle access layer (pool, read-only transactions, metadata)
sqlGuard.ts static SQL validation
reports.ts report registry, parameter validation, PL/SQL call builder
config.ts environment configuration (zod)
config/reports.json curated report registry
docker/init/ schema, seed data, report package, read-only user
tests/ unit + integration tests (node:test)Roadmap
MCP resources for schema documentation and prompts for common analyses
Optional table/column allow-list and PII masking
Streamable HTTP transport with authentication
Export results as CSV/Excel
License
MIT © Gökhan Hepyetiker
Available Tools
5 toolsdescribe_tableDescribe ERP tableARead-onlyIdempotent
Show columns, data types, comments, primary key and foreign keys of a table or view. Use it before writing SQL.
Inputs: table (required).
list_reportsList curated reportsBRead-onlyIdempotent
List curated, pre-approved ERP reports (PL/SQL procedures returning SYS_REFCURSOR) and their parameters.
Inputs: no named parameters.
list_tablesList ERP tablesBRead-onlyIdempotent
List tables and views in the ERP schema with their business descriptions.
Inputs: filter.
run_queryRun read-only SQLARead-onlyIdempotent
Execute a single Oracle SELECT/WITH statement and return at most 200 rows as JSON. Data-changing statements, PL/SQL, DB links and DBMS_/UTL_ packages are rejected.
Inputs: sql (required), max_rows.
run_reportRun curated reportARead-onlyIdempotent
Run a curated report by name. Use list_reports to see available reports and parameters.
Inputs: name (required), params, max_rows.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: listing vs running curated reports, listing vs describing tables, and a separate ad-hoc query tool. There is no overlap between the discovery tools and the execution tools.
All five tools follow a consistent verb_noun snake_case pattern (list_reports, run_report, list_tables, describe_table, run_query). The convention is predictable throughout.
Five tools is well-scoped for a read-only ERP query/reporting interface, with each tool earning its place across discovery and execution. No redundant or trivial tools.
The surface covers the full read-only lifecycle: discover reports and tables, inspect schema, and execute both curated and ad-hoc queries. Minor gaps like pagination beyond the 200-row cap or schema search are workable but slightly limiting.
Maintenance
Related MCP Connectors
Claude, connected to your own Oracle EPM. Each person as themselves, every call checked and logged.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Read-only finance and operations controls for AI agents with evidence and safe next actions.
Query, explore, and manage your databases through natural conversation.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI tools to interact with Oracle databases through query execution, schema browsing, stored procedure calls, and transaction management. Supports multiple database connections with safety features like read-only mode and dangerous query detection.16MIT
- AlicenseBqualityDmaintenanceRead-only access to Oracle Fusion Cloud ERP data via natural language queries, with support for accounts payable, procurement, general ledger, and more.3028 PyPI4MIT
- FlicenseNot gradedqualityDmaintenanceEnables read-only exploration of Oracle databases through natural language, providing schema inspection and safe bounded SQL query execution.-
- FlicenseNot gradedqualityDmaintenanceEnables 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.-