cledara-mcp
# cledara-mcp
A read-only [MCP](https://modelcontextprotocol.io) server for [Cledara](https://www.cledara.com), the SaaS and spend management platform. It lets Claude (or any MCP client) look up your applications, transactions, invoices, spend, renewals and people.
It wraps the [Cledara public API](https://api-docs.cledara.com) (v0). That API is read-only, and so is this server: no tool can change anything in Cledara.
## Read-only by design
This server cannot change anything in Cledara:
- **Requests:** it only ever makes HTTP `GET` requests, and only to `/v0/applications`, `/v0/transactions` and `/v0/transactions/{id}/invoice-url`. A test fails the build if any tool sends another kind of request or calls another path.
- **Tools:** every tool is marked `readOnlyHint: true` and `destructiveHint: false`, so MCP clients know none of them have side effects.
- **Local files:** it writes nothing to disk. The only cache is an in-memory copy of the application list.
- **The Cledara API (v0):** it has no write endpoints at all.
A Cledara API key carries all the permissions of the user who created it, and Cledara has no read-only key type. If Cledara adds write endpoints later, this server still won't call them, but the key itself could. Treat the key like a password.
## Tools
| Tool | What it does |
|---|---|
| `list_applications` | Apps with status, owner, teams, budget, balance, next renewal and next payment. Filter by status, name, owner or team. |
| `list_transactions` | Raw transactions for a date range (default: last 30 days), optionally for specific apps or transaction types. Paginated. |
| `get_invoice_url` | Download link for a transaction's invoice (valid for 5 minutes). |
| `spend_summary` | Spend over a date range grouped by application, team, owner, card, month or account type, totalled per currency. |
| `upcoming_renewals` | Apps renewing or due a payment in the next N days (default 30) with the expected amount. Cledara often leaves the renewal date empty, so the expected next payment date is used instead (`dateSource` says which). |
| `missing_invoices` | Card payments with no invoice uploaded, for month-end close. |
| `list_people` | People and teams, inferred from app owners and cardholders (Cledara has no users endpoint). |
How the computed tools work:
- **Spend** counts card payments (`cardSend`) net of refunds (`cardReceive`), plus `reimbursement`. Debits are shown as positive numbers. Top-ups, flushes and transfers are left out because they only move money between Cledara accounts. You can override this with `transactionTypes`.
- **Currencies are never converted.** Every total is per currency.
- **Team totals:** an app assigned to several teams counts in full under each team.
- **Owner:** the application owner when the payment is for an app, otherwise the cardholder.
- **Large ranges:** aggregate tools fetch up to 50 API pages. If a range has more, the result includes a `warning`.
## Requirements
- Node.js 20.12 or later. Running the tests or `npm run dev` needs Node 23.6 or later.
- A Cledara API key. Only users with the **SaaS Admin/Finance** or **Spend Admin/Accountant** role can create one: in Cledara, go to **Profile → API Keys → Create API key**.
- **The key can see everything the user who created it can see.** Create it from the least-privileged eligible user and give it an expiry.
- Each key works for one Cledara account only.
## Install
### Option A: clone (recommended for development)
```sh
git clone https://github.com/ilyesBen/cledara-mcp.git
cd cledara-mcp
npm install # also builds dist/
cp .env.example .env # then paste your key after CLEDARA_API_KEY=
chmod 600 .env
claude mcp add --scope user cledara -- node "$PWD/dist/index.js"
```
### Option B: straight from GitHub with npx
```sh
mkdir -p ~/.config/cledara-mcp
printf 'CLEDARA_API_KEY=\n' > ~/.config/cledara-mcp/.env # then paste your key
chmod 600 ~/.config/cledara-mcp/.env
claude mcp add --scope user cledara -- npx -y github:ilyesBen/cledara-mcp
```
### Claude Desktop (one-click extension)
[Download `cledara.mcpb`](https://github.com/ilyesBen/cledara-mcp/releases/latest/download/cledara.mcpb) and double-click it. Claude Desktop asks for your API key and stores it in the system keychain. Node.js isn't needed.
There's a step-by-step guide for non-technical users in [docs/claude-desktop.md](docs/claude-desktop.md).
To build the extension yourself, run `npm run mcpb`. It writes `build/cledara.mcpb`. To publish a release, bump `version` in `package.json`, then push a matching `vX.Y.Z` tag; the Release workflow builds the extension and attaches it.
### Other MCP clients
For Claude Desktop, Cursor and similar clients, add this to the client's MCP config:
```json
{
"mcpServers": {
"cledara": { "command": "npx", "args": ["-y", "github:ilyesBen/cledara-mcp"] }
}
}
```
`--scope user` makes the server available in every Claude Code project. Use `--scope project` to write it to a shared `.mcp.json` instead.
## Configuration
| Variable | Default | Purpose |
|---|---|---|
| `CLEDARA_API_KEY` | — | Required. Your Cledara API key. |
| `CLEDARA_ENV_FILE` | — | Path to an env file to read the key from. |
| `CLEDARA_API_BASE_URL` | `https://api.cledara.com` | Override the API host, e.g. for a mock server. |
The server takes the first non-empty key it finds, in this order:
1. The process environment
2. `$CLEDARA_ENV_FILE`
3. `.env` in the package root (a git clone)
4. `~/.config/cledara-mcp/.env`
Prefer an env file over `claude mcp add -e CLEDARA_API_KEY=...`, which stores the key in plain text in `~/.claude.json`.
The key is only ever sent to the Cledara API in the `Authorization` header. It is never logged or included in error messages.
## Rate limits
Cledara allows 120 requests per minute per key. The server:
- Limits itself to 100 requests per minute, so other users of the key keep some headroom.
- When it gets a `429`, waits for the time in `Retry-After` and retries, up to 3 times.
- Caches the application list for 5 minutes.
## Development
```sh
npm test # unit, server and stdio end-to-end tests against mocks (no API key needed)
npm run typecheck
npm run build # compiles src/ to dist/
npm run dev # runs src/index.ts directly
```
The tests use synthetic fixtures based on Cledara's published OpenAPI spec and never call the real API.
You can try the server interactively with the MCP Inspector: `npx @modelcontextprotocol/inspector node dist/index.js`.
TDQS
Scored across 7 tools
Each tool targets a clearly distinct resource or analytical view: applications, people, raw transactions, invoice URLs, spend summaries, renewals, and missing invoices. The boundaries between raw transactions, spend summaries, overdue invoices, and renewals are well described, so an agent can select the right tool without confusion.
All names use snake_case, but the naming conventions are mixed: list_* and get_* verb-noun tools coexist with noun-phrase tools like spend_summary, upcoming_renewals, and missing_invoices. The names remain readable and understandable, but the pattern is not fully predictable.
Seven tools is a well-scoped size for a read-only SaaS spend reporting integration. Each tool fills a specific reporting or lookup need without redundant or filler operations.
The surface covers the core Cledara reporting workflows: applications, people, transactions, invoices, spend summaries, renewals, and missing invoices. Minor gaps exist, such as no dedicated application-detail or card-listing endpoint, but most needs can be worked around using filters and summaries.