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?"

Related MCP server: invoiceninja-mcp

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

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

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