# Elorus MCP Server

**A read-only [Model Context Protocol](https://modelcontextprotocol.io) server for the [Elorus](https://www.elorus.com) invoicing platform — ask your business data questions in plain language.**

[![CI](https://github.com/nikagabriel741agent/Elorus-ERP-MCP-Server/actions/workflows/ci.yml/badge.svg)](https://github.com/nikagabriel741agent/Elorus-ERP-MCP-Server/actions/workflows/ci.yml)
![Python](https://img.shields.io/badge/python-3.11%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

> **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

```mermaid
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`):

```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:**

```bash
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

```bash
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

```bash
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](LICENSE)