ERP数据管理MCP服务器

Umbra ERP MCP Server

An MCP (Model Context Protocol) server that enables AI agents to manage ERP data through the Umbra ERP public API. Supports customers, invoices, quotes, products, payments, receipts, recurring invoice and quote schedules, supplier bills and payments, journal entries, aged receivables, customer statements, employees, leave requests, webhooks, and CRM contacts, leads and activities.

Quick Start

1. Get an API Key

Sign up at umbraerp.com and generate an API key from Settings > API Keys. Secret keys (usk_*) have access to sensitive employee data; publishable keys (uk_*) do not.

2. Install

# Clone the repo
git clone https://github.com/Lioncap-Ventures/umbra-mcp.git
cd umbra-mcp

# Install dependencies
pip install mcp httpx

3. Configure

Set your API key via environment variable or add it to a .env file:

# Option A: Environment variable
export UMBRA_API_KEY="usk_live_your_key_here"

# Option B: Add to ~/.claude/scripts/.env (for Claude Code)
echo 'UMBRA_API_KEY=usk_live_your_key_here' >> ~/.claude/scripts/.env

4. Register with Claude Code

Add to ~/.claude/.mcp.json:

{
  "mcpServers": {
    "umbra": {
      "command": "python3",
      "args": ["/path/to/umbra-mcp/server.py"]
    }
  }
}

Then restart Claude Code. The Umbra ERP tools will be available in all conversations.

5. Run Standalone

python3 server.py

Money units

Every amount a tool takes or returns is in dollars (150.00), never cents. That includes record_bill_payment, whose amount is dollars end to end. Do not convert.

The reports return Cents twins (bucketsCents, totalCents, closingBalanceCents) in integer cents. Use those for comparison and summation and the dollar fields for display; float sums drift.

Identifiers

Every id you pass to a tool is a public UUID. A few nested response fields are numeric row ids instead and must never be fed back into a tool: recurring*.customerId, bill.vendorId, customer_statement.payments[].invoiceId, recurring_quote.lastGeneratedQuoteId, journal.sourceId and journal.lines[].accountId.

Available Tools (67)

Customers

Invoices

Products

Quotes

Payments

Employees

Leave Requests

Webhooks

Receipts

Pay links and quote conversion

Recurring schedules

Reports

Bills (accounts payable)

Journal entries (read-only)

There is deliberately no journal write tool. Entries are posted from real events; a hand-made entry would be a figure in the ledger with no document behind it.

CRM

System

Authentication

All requests use the X-Api-Key header. API keys come in two types:

Keys are scoped by permissions. Your key only reaches the resources it holds a scope for:

bills, journal, reports, employees and payroll only became grantable on 2026-08-29. A key minted before that date cannot hold them and returns 403 on those endpoints. Re-mint the key with the scopes you need.

Rate Limits

• 100 requests/minute per API key
• 1,000 requests/hour per API key
• Rate limit headers (X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Hour) included in responses

Webhook Events

Register webhooks to receive real-time notifications:

customer.created, customer.updated, customer.deleted
invoice.created, invoice.updated, invoice.deleted
product.created, product.updated, product.deleted
quote.created, quote.updated, quote.deleted
payment.created
employee.created, employee.updated, employee.deleted
leave.created, leave.updated, leave.deleted

Payloads are signed with HMAC-SHA256 via the X-Webhook-Signature header.

Configuration

Every tool takes an optional workspace argument (default primary).

Workspace environment binding

Pairing UMBRA_API_KEY_<NAME> with UMBRA_API_URL_<NAME> is convention, not something the code can enforce in general. A key is bound to one business and one environment, so a mismatched pair fails safe: the request simply 401s rather than reaching the wrong business.

One direction is asserted, because it is unambiguous and the failure would be pointing real credentials at a test system: a live key (usk_live_* / uk_live_*) sent to a host whose URL contains staging is refused before the request leaves.

The reverse is deliberately not asserted. environment is a column on the key, not a property of the host, and production currently serves active test-environment keys, so refusing a usk_test_* key against a non-staging host would break a real configuration.

Tests

../.venv/bin/python test_request_shapes.py

Offline request-shape checks: they replace httpx.Client with a recorder and assert the exact method, path, headers and JSON body every write tool sends. No network, no API key, no database, so a mutation tool can be verified without pointing it at a live business.

API Documentation

• Interactive docs: {API_URL}/api/docs (Swagger UI)
• ReDoc: {API_URL}/api/redoc

License

MIT