ERP MCP Agent

Ask your ERP questions in plain English, safely. This project connects Claude to business data (customers, stock, orders, invoices, payments) through a read-only MCP server. Staff can ask "Which products are below reorder level?" or "Is Oakhurst over its credit limit?" in Claude Desktop and get answers from live data. Two Claude Skills turn recurring office work (a weekly sales summary, customer payment reminders) into one-sentence requests.

The demo runs on a realistic, fully synthetic ERP database. The same pattern plugs into SQL Server, PostgreSQL or an existing ERP such as Netsis, Logo or Odoo (see Adapting it to your ERP).

🎬 Demo video: 2-minute walkthrough — link coming soon

flowchart LR
    U([Employee]) --> CD[Claude Desktop<br/>+ Skills]
    CD <-->|MCP| S[ERP MCP server<br/>5 read-only tools]
    S -->|parameterized SELECT| D[(ERP database)]
    S -->|every call| L[[Audit log]]

What it can do

get_kpi metrics: revenue, top_products, top_customers, avg_order_value, overdue_receivables.

Sample outputs: docs/sample-outputs.md

Related MCP server: legacy-db-mcp

Quick start (about 5 minutes)

Requirements: Python 3.11+, Claude Desktop, Git.

1. Install

Windows (PowerShell)

git clone https://github.com/burakOzden1/erp-mcp-agent.git
cd erp-mcp-agent
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe scripts\seed_db.py

macOS / Linux

git clone https://github.com/burakOzden1/erp-mcp-agent.git
cd erp-mcp-agent
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python scripts/seed_db.py

seed_db.py creates data/erp_demo.db and prints the row counts and the planted demo situations (9 products below reorder level, 12 late orders, 6 customers with partially paid overdue invoices, 2 customers over their credit limit).

2. Connect Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config and add the server under mcpServers (keep any servers you already have):

Windows

{
  "mcpServers": {
    "erp-demo": {
      "command": "C:\\path\\to\\erp-mcp-agent\\.venv\\Scripts\\erp-mcp.exe"
    }
  }
}

macOS

{
  "mcpServers": {
    "erp-demo": {
      "command": "/path/to/erp-mcp-agent/.venv/bin/erp-mcp"
    }
  }
}

Fully quit Claude Desktop (tray / menu bar → Quit) and reopen it. The five erp-demo tools appear under the tools icon in a new chat.

3. Add the Skills (optional)

python scripts/package_skills.py

This writes dist/skills/weekly-sales-summary.zip and dist/skills/customer-email-draft.zip. In Claude Desktop, go to Settings → Capabilities, make sure code execution is on, and upload both zips under Skills.

Example questions and answers

With the default dataset (data as of 2026-10-31):

Typos are handled: asking about "Oakhust" returns "Did you mean: Oakhurst Facilities Group (C-0007)?"

Security approach

Giving an AI model access to business data needs to be boring and predictable. This server is designed so that the worst a confused prompt can do is read a limited amount of data, and every read is recorded.

• Read-only by construction. The database is opened with SQLite's mode=ro and PRAGMA query_only = ON. Tools carry MCP readOnlyHint / destructiveHint=false annotations. Tests confirm that INSERT, UPDATE, DELETE and DROP fail.

• No free-form SQL. Claude cannot send SQL. Each tool runs one pre-written query with bound parameters; the KPI tool accepts only a fixed list of metrics.

• Bounded results. List tools return at most 50 rows and say when more exist.

• Audit trail. Every tool call (successful or not) is appended to logs/audit.jsonl:

  {"ts": "2026-10-28T18:26:45.327+00:00", "tool": "get_stock", "params": {"query": "", "category": null, "below_reorder_only": true}, "row_count": 9, "duration_ms": 2.29, "status": "ok"}

• Human in the loop. The email Skill only drafts; a person reviews and sends.

• Local by default. The server runs on your machine over stdio. No ports are opened, and the demo needs no credentials.

More detail: docs/architecture.md.

Adapting it to your ERP

The tool contract (names, parameters, JSON shape), audit log and Skills are independent of the database. Moving to a real system touches two files: db.py (connection) and queries.py (SQL).

1. Pick the access path. Connect to a reporting replica or read-only views rather than the production schema. Create a dedicated database user with SELECT permission on those views only.

2. Map the concepts. Every ERP has the same six building blocks: customer accounts, items/stock, sales orders and lines, invoices, and payments. Document which tables or views hold each, plus the status codes for open/shipped/delivered/cancelled.

3. Swap the connection. Replace sqlite3 with pyodbc (SQL Server), psycopg (PostgreSQL) or the ERP's API/ODBC driver. Keep the read-only guarantees at the database-user level.

4. Port the queries. Rewrite the SQL in queries.py for the new schema and keep the returned JSON fields the same, so Claude and the Skills need no changes.

5. Add business rules. Multi-currency, branches or warehouses, VAT, credit control rules: add them as tool parameters or new fixed metrics, never as free SQL.

6. Harden for production. Add authentication if the server is exposed over HTTP, ship the audit log to your log platform, and apply row-level filters per user or role.

Typical targets: Microsoft SQL Server based ERPs (e.g. Netsis, Logo), PostgreSQL based systems (e.g. Odoo), or accounting platforms with REST APIs (e.g. QuickBooks Online).

Project structure

erp-mcp-agent/
├── src/erp_mcp/
│   ├── server.py        # MCP server and the 5 tool definitions
│   ├── queries.py       # parameterized SQL and KPI logic
│   ├── db.py            # read-only connection
│   └── audit.py         # JSON Lines audit log
├── skills/
│   ├── weekly-sales-summary/SKILL.md
│   └── customer-email-draft/SKILL.md
├── scripts/
│   ├── seed_db.py       # builds the synthetic ERP database
│   └── package_skills.py
├── tests/               # pytest: queries, MCP protocol, audit, skills, data integrity
└── docs/                # architecture, demo script, sample outputs

Development

python -m pytest            # 52 tests, about 2 seconds
python scripts/seed_db.py --as-of today   # re-anchor the demo data to today's date

Configuration via environment variables: ERP_DB_PATH (database file) and ERP_AUDIT_LOG (log file).

Windows: quit Claude Desktop before re-running pip install. While Claude Desktop runs the server, Windows locks .venv\Scripts\erp-mcp.exe and the reinstall fails halfway.

Built with the official MCP Python SDK (mcp 2.3).

License

MIT