Elorus MCP Server

A read-only Model Context Protocol server for the Elorus invoicing platform — ask your business data questions in plain language.

Unofficial & read-only. This project is not affiliated with Elorus. It only ever issues GET requests — it cannot create, modify, or delete anything in your organization.

What can you ask?

• "Which invoices are overdue, and for how much?"
• "How much did we invoice ACME Ltd in July?"
• "What did we spend on hosting last month?"
• "Which payments did we receive this week?"
• "What is the VAT number of client X?"

Features

• 10 read-only tools covering invoices, contacts, expenses, cash receipts and products (Elorus API v1.2)
• Curated filters — period, status, paid/unpaid, overdue, client/supplier, free-text search — documented in every tool schema so the LLM calls them correctly
• Token-efficient responses — list tools return trimmed summaries; get_* tools return the full record
• Read-only by construction — the HTTP client implements GET only
• Clear error messages for authentication, rate-limit and connectivity problems

Architecture

flowchart LR
    A["MCP client (Claude Desktop / Claude Code)"] -- stdio --> B["elorus-mcp (MCP Python SDK)"]
    B --> C["ElorusClient (GET-only, httpx)"]
    C -- "Authorization: Token + X-Elorus-Organization" --> D["Elorus API v1.2"]

Quickstart

1. Get your credentials

• API key: Elorus web app → User Profile → API token
• Organization ID: Elorus web app → Settings → Organization → Organization ID

2. Configure your MCP client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "elorus": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/nikagabriel741agent/Elorus-ERP-MCP-Server", "elorus-mcp"],
      "env": {
        "ELORUS_API_KEY": "your-api-key",
        "ELORUS_ORGANIZATION_ID": "your-organization-id"
      }
    }
  }
}

Claude Code:

claude mcp add elorus \
  -e ELORUS_API_KEY=your-api-key \
  -e ELORUS_ORGANIZATION_ID=your-organization-id \
  -- uvx --from git+https://github.com/nikagabriel741agent/Elorus-ERP-MCP-Server elorus-mcp

Local development install

git clone https://github.com/nikagabriel741agent/Elorus-ERP-MCP-Server.git
cd Elorus-ERP-MCP-Server
uv sync
cp .env.example .env   # fill in your credentials
uv run --env-file .env elorus-mcp

Tools

Tool	Description	Key arguments
list_invoices	List sales invoices (summaries)	period_from, period_to, status, paid, overdue, draft, client, search, ordering, page, page_size
get_invoice	Full invoice record	invoice_id
list_contacts	List clients & suppliers	search, contact_type (client/supplier), active, page, page_size
get_contact	Full contact record	contact_id
list_expenses	List expenses	period_from, period_to, supplier, search, page, page_size
get_expense	Full expense record	expense_id
list_cash_receipts	List payments received	period_from, period_to, contact, invoice, transaction_type, page, page_size
get_cash_receipt	Full cash receipt record	cash_receipt_id
list_products	List products & services	search, active, sales, purchases, page, page_size
get_product	Full product record	product_id

Notes: dates are YYYY-MM-DD; period_from/period_to only apply when both are set. Invoice status is one of draft, pending, issued, partial, unpaid, overdue, paid, void.

Configuration

Environment variable	Required	Description
ELORUS_API_KEY	yes	Personal API key (Elorus web app → User Profile)
ELORUS_ORGANIZATION_ID	yes	Elorus web app → Settings → Organization → Organization ID
ELORUS_BASE_URL	no	Defaults to https://api.elorus.com/v1.2

Development

uv sync                        # install dependencies
uv run pytest -v               # run the test suite (no real API calls)
uv run ruff check .            # lint
uv run ruff format --check .   # formatting

License

MIT