Skip to main content
Glama
mcp-erp-server

mcp-erp-server

by aldemarluz
README.md
# mcp-erp-server

**A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI assistants query an ERP — with per-department access, provenance on every answer, and read-only by default.**

Connecting an assistant to company systems is easy. Connecting it *safely* is the real work: a sales rep should not be able to ask about payables, a director should be able to read everything without being able to change anything, and every number the assistant repeats should be traceable to where it came from.

This server shows that pattern over a small synthetic ERP (sales, procurement, finance, inventory).

```
$ ERP_PROFILE=buyer npm start
mcp-erp-server running for profile "buyer"
tools: procurement_open_orders, inventory_stock          ← nothing from sales or finance
```

## Three rules

```mermaid
flowchart LR
    A[AI assistant] -->|MCP| S[mcp-erp-server]
    P[Access profile<br/>per department:<br/>none / read / write] --> S
    S -->|registers only<br/>allowed tools| T[Tools]
    T --> D[(ERP adapters)]
    T -->|data + provenance| A
```

**1. Access by profile — at registration time.**
Each person has a profile with a level per department (`none`, `read`, `write`). Tools for departments they can't use are **never registered**, so the assistant doesn't even know they exist for that person. That is stronger than refusing at call time: there is no tool name to probe and nothing to talk the model into.

| Profile | sales | procurement | finance | inventory |
|---|---|---|---|---|
| `director` | read | read | read | read |
| `sales_manager` | **write** | – | read | read |
| `sales_rep` | read | – | – | read |
| `buyer` | – | read | – | read |

**2. Provenance on every answer.**
Every response is an envelope with the data *and* where it came from:

```json
{
  "data": [ { "id": "SO-1001", "status": "confirmed", "total": 3900 } ],
  "provenance": {
    "source": "sales.orders",
    "filters": { "status": "confirmed", "limit": 20 },
    "records": 1,
    "queried_at": "2026-11-18T12:00:00.000Z",
    "profile": "sales_rep"
  }
}
```

The assistant can cite it, and a person can check it. A number without a source is not an answer.

**3. Read-only by default; writes are explicit.**
There is one write tool, `sales_update_order_status`. It exists only for profiles with `write` on sales, it accepts only valid status transitions (`quote → confirmed → invoiced → shipped`, or `cancelled` before invoicing), and **without `confirm: true` it returns a dry-run preview** of the change instead of making it. Repeating a write that is already in place changes nothing.

## Tools

| Tool | Department | What it answers |
|---|---|---|
| `sales_find_customer` | sales · read | Find a customer by name, id or tax id |
| `sales_list_orders` | sales · read | Orders by status / customer, with computed totals |
| `sales_get_price` | sales · read | Tier price for a customer, and whether it is under the floor price |
| `sales_update_order_status` | sales · **write** | Move an order to a new status (dry run unless `confirm: true`) |
| `procurement_open_orders` | procurement · read | Purchase orders not fully received, pending quantity per line |
| `finance_receivables` | finance · read | Open / overdue invoices and the total |
| `inventory_stock` | inventory · read | On-hand, reserved, available and shortages per location |

## Use it with Claude Desktop (or any MCP client)

```json
{
  "mcpServers": {
    "erp": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-erp-server/src/index.ts"],
      "env": { "ERP_PROFILE": "sales_rep" }
    }
  }
}
```

Then ask things like *"Which of Northwind's orders are still open, and do we have stock to ship them?"* — the assistant chains `sales_find_customer → sales_list_orders → inventory_stock`, and every figure in its answer carries its source.

## Run it

```bash
npm install
npm test                       # 19 tests, end to end through a real MCP client
ERP_PROFILE=director npm start # stdio server
```

## Project layout

```
src/access.ts   profiles and the can(profile, department, level) check
src/data.ts     synthetic ERP data (swap for adapters over real systems)
src/server.ts   tool registration per profile, provenance envelope, the write gate
src/index.ts    stdio entry point (profile from ERP_PROFILE)
test/           19 tests using the MCP SDK's in-memory client/server pair
```

## Context

A generic, clean-room implementation of a pattern for giving AI assistants safe access to business systems: scoped by role, explicit about where every number comes from, and unable to change data without confirmation. All names and data here are synthetic.

MIT licensed.

TDQS

B3.3/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a distinct resource and action: customer lookup, order listing, price lookup, order status transition, receivables, and stock levels. No two tools could plausibly be confused for one another, and the domain prefixes further separate sales, finance, and inventory concerns.

Naming Consistency4/5

The pattern is namespace_verb_noun (sales_find_customer, sales_list_orders, sales_update_order_status), applied consistently within the sales namespace. The finance_receivables and inventory_stock tools drop the verb and read as nouns, a minor but noticeable deviation from the rest of the set.

Tool Count4/5

Six tools is a lean, well-scoped surface where each tool maps to a clear question an ERP assistant would ask. It is on the thin side for a system as broad as an ERP, but nothing feels padded or redundant.

Completeness3/5

The set covers read paths for customers, orders, pricing, receivables, and stock, plus one guarded write (order status). However, there is no order creation, no customer or inventory write operations, and no invoice or line-item detail retrieval, leaving notable gaps for a full ERP lifecycle.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues