Skip to main content
Glama

easybill MCP Server

An MCP server for the easybill REST API. Gives any MCP-capable assistant — Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed, Codex CLI, Gemini CLI, Cline — access to your invoices, customers, article catalogue, payments, projects and tracked time.

Built on the official @modelcontextprotocol/sdk (TypeScript), talking stdio.

  • 64 tools across 13 easybill resources (65 in hosted mode)

  • Read-only by default — create/update/delete tools stay unregistered unless you opt in

  • Workflow-aware — ships server instructions so the agent resolves the customer before writing a document, instead of guessing where to start

  • Fuzzy customer search the easybill API itself does not offer

  • Self-throttling to respect easybill's 10–60 requests/minute cap

  • Context-aware responses — compact field sets, pagination metadata, automatic truncation


Setup

1. Get an easybill API key

In easybill: Einstellungen → App-Center → API. Create a key and copy it.

2. Register it with your client

This is a plain stdio MCP server published on npm, so any MCP client can run it with npx — no clone, no build, no global install:

npx -y easybill-mcp

Configuration is entirely through environment variables (full list under Configuration). Two matter now:

  • Leave EASYBILL_ENABLE_WRITES unset to start read-only.

  • Set EASYBILL_RATE_LIMIT_PER_MINUTE to 10 on easybill's Professional plan or 60 on Premium (Free and Starter have no API access).

Most clients use the same JSON shape under an mcpServers key:

{
  "mcpServers": {
    "easybill": {
      "command": "npx",
      "args": ["-y", "easybill-mcp"],
      "env": {
        "EASYBILL_API_KEY": "your_api_key_here",
        "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
      }
    }
  }
}

Where that block goes:

Client

Config location

Claude Desktop

Settings → Developer → Edit Config, or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (per project)

Windsurf

~/.codeium/windsurf/mcp_config.json

Cline / Roo Code

MCP Servers panel → Configure MCP Servers (cline_mcp_settings.json)

Gemini CLI

~/.gemini/settings.json

Claude Code

claude mcp add, see below

VS Code / Copilot

.vscode/mcp.json, different key — see below

Zed

settings.json → context_servers, see below

Codex CLI

~/.codex/config.toml, TOML instead of JSON — see below

Windows: if a client fails to start npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "easybill-mcp"].

Claude Code

claude mcp add easybill \
  --env EASYBILL_API_KEY=your_api_key_here \
  --env EASYBILL_RATE_LIMIT_PER_MINUTE=10 \
  -- npx -y easybill-mcp

claude mcp add does not overwrite an existing entry — to change the environment later, claude mcp remove easybill -s local first, then add it again.

VS Code (GitHub Copilot agent mode)

VS Code uses servers, not mcpServers, and can prompt for the key instead of storing it in the file. Put this in .vscode/mcp.json (workspace) or open MCP: Open User Configuration:

{
  "inputs": [
    { "id": "easybill_key", "type": "promptString", "description": "easybill API key", "password": true }
  ],
  "servers": {
    "easybill": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "easybill-mcp"],
      "env": {
        "EASYBILL_API_KEY": "${input:easybill_key}",
        "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
      }
    }
  }
}

Zed

In settings.json:

{
  "context_servers": {
    "easybill": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "easybill-mcp"],
      "env": {
        "EASYBILL_API_KEY": "your_api_key_here",
        "EASYBILL_RATE_LIMIT_PER_MINUTE": "10"
      }
    }
  }
}

Codex CLI

In ~/.codex/config.toml:

[mcp_servers.easybill]
command = "npx"
args = ["-y", "easybill-mcp"]
env = { EASYBILL_API_KEY = "your_api_key_here", EASYBILL_RATE_LIMIT_PER_MINUTE = "10" }

Hosted clients that only speak remote MCP

For claude.ai and other remote-only clients, run the server in hosted mode (see "Hosted mode" below): one connector for the whole company, each person connects the easybill accounts they use with their personal API key.

For a quick single-user experiment you can instead bridge the stdio server locally:

npx -y supergateway --stdio "npx -y easybill-mcp"

Only do this if you understand the exposure: anything that reaches that endpoint reaches your accounting data. Keep it bound to localhost or behind a tunnel with authentication, and never run the bridge with writes enabled unless the endpoint is protected.

3. Verify the connection

Ask the assistant to call easybill_get_server_info. It reports the mode, the limits and whether easybill accepted the credentials:

{
  "server_version": "1.0.1",
  "writes_enabled": false,
  "tools_registered": { "read_only": 28, "write": 0, "withheld_because_writes_disabled": 26 },
  "rate_limit_per_minute": 10,
  "connection": "ok — credentials accepted by easybill"
}

4. Enable writes, once you trust it

Add EASYBILL_ENABLE_WRITES=true to the server's environment:

claude mcp add easybill \
  --env EASYBILL_API_KEY=your_api_key_here \
  --env EASYBILL_RATE_LIMIT_PER_MINUTE=10 \
  --env EASYBILL_ENABLE_WRITES=true \
  -- npx -y easybill-mcp

The 26 write tools are registered at startup, so the change only takes effect once the client restarts the server process — editing the config in a running session is not enough. Confirm with easybill_get_server_info: writes_enabled must read true.


Related MCP server: billingo-mcp

Running from a local clone

For development, or to run a version you have not published:

git clone https://github.com/stack74/easybill-mcp.git
cd easybill-mcp
npm install
npm run build

Then point the client at the built entry point instead of npx — "command": "node", "args": ["/absolute/path/to/easybill-mcp/dist/index.js"], same env block. Or straight from GitHub without cloning, which is slower because it compiles TypeScript on install via the prepare script and needs a toolchain:

npx -y github:stack74/easybill-mcp

Test locally first

Copy .env.example to .env, put your key in it, then run the read-only self-test:

cp .env.example .env
$EDITOR .env
npm run smoke

It makes five read-only calls and prints what came back:

easybill-mcp-server v1.x.y self-test
API: https://api.easybill.de/rest/v1
Throttle: 60 req/min | writes disabled

  OK    Auth check (customer groups): total=2  first=Stammkunden
  OK    Customers: total=42  first=Example GmbH
  OK    Invoices: total=128  first=RE-2026-0001
  OK    Unpaid invoices: total=7  first=RE-2026-0117
  OK    Articles (positions): total=95  first=ART-001

All probes passed. The server is ready to register with an MCP client.

(Numbers above are illustrative — you will see your own account's totals.)

On a bad key it fails on the first call and stops, so it never burns your rate limit.

To poke at individual tools interactively:

npm run inspect     # MCP Inspector, loads .env

Note: .env is only read by these npm scripts, via Node's --env-file. The server itself reads plain environment variables — when you register it with an MCP client, pass the key through the client's config, not via .env.

Publishing to npm

npm login                  # once, needs an npmjs.com account
npm run build && npm run smoke
npm publish                # unscoped packages are public by default

Verify what ships before you publish — npm pack --dry-run lists the tarball contents. Only dist/, README.md, LICENSE and package.json are included; src/ and .env are not.

For later releases bump the version first (npm version patch|minor|major), which also creates a git tag. npm does not allow republishing an existing version.


Hosted mode (claude.ai connector, several easybill accounts)

easybill-mcp --http runs the server as a remote MCP endpoint (Streamable HTTP) for a whole company:

  1. Someone adds the connector in claude.ai (or any OAuth-capable MCP client).

  2. The client opens this server's connect page. It lists the easybill accounts from your tenant configuration; the person clicks Verbinden on each account they have access to and pastes their personal easybill API key (easybill: user icon → Profil und Einstellungen → API Key). The server checks it against easybill before storing it.

  3. Fertig – zurück zu Claude completes the client's OAuth flow.

Every tool then takes an account argument (easybill_list_accounts shows the status and hands out a link to connect more accounts or replace a key). Keys are stored AES-GCM encrypted in SQLite. A key easybill rejects later (regenerated, login removed) is marked and the model hands out the link to replace it.

This server is the OAuth authorization server for the MCP client (claude.ai); easybill itself only sees API-key requests. An API key does not say which easybill account it belongs to, so on the first connection of a tenant the server remembers the account's login IDs (from /logins) and refuses later keys from a different account, including a key that already belongs to another configured tenant.

easybill OAuth instead of API keys (EASYBILL_CONNECT_MODE=oauth): people log in at easybill instead of pasting a key. easybill only allows dynamic client registration for an allowlist of redirect URIs (claude.ai and similar), so this mode needs an OAuth client issued by easybill for <EASYBILL_PUBLIC_URL>/connect/callback (EASYBILL_OAUTH_CLIENT_ID / _SECRET).

Tenant configuration

{
  "tenants": [
    { "id": "firma-a", "name": "Firma A GmbH", "plan": "PREMIUM", "writes": true },
    { "id": "firma-b", "name": "Firma B GmbH", "plan": "PROFESSIONAL", "writes": false }
  ]
}

Field

Meaning

id

Slug the model passes as account.

name

Shown on the connect page and to the model.

plan

PROFESSIONAL (10 req/min) or PREMIUM (60 req/min); the former names PLUS / BUSINESS work too. Free and Starter have no API access. Throttle shared by everyone on the account. Or set rate_limit_per_minute.

writes

true registers create/update/delete for this account and requests write scopes from easybill. Default read-only scopes.

scopes

Optional override of the easybill OAuth scopes.

match

OAuth mode only: { "<claim>": "<value>" } checked against easybill's access-token claims, so a login of the wrong company is refused. The server logs the claims of every new connection.

Environment

Variable

Default

Purpose

EASYBILL_PUBLIC_URL

—

Required. Public https base URL. The connector URL is <this>/mcp.

EASYBILL_MCP_SECRET

—

Required. ≥ 32 characters; encrypts stored tokens and signs the browser cookie. Changing it invalidates all connections.

EASYBILL_TENANTS_FILE / EASYBILL_TENANTS

—

Required. Path to the tenant JSON, or the JSON inline.

EASYBILL_DB_PATH

./data/easybill-mcp.sqlite

SQLite file. Put it on a persistent volume.

PORT / HOST

3000 / 0.0.0.0

Listen address.

EASYBILL_CF_ACCESS_TEAM_DOMAIN / EASYBILL_CF_ACCESS_AUD

—

Put the connect pages behind Cloudflare Access: team domain (e.g. acme or acme.cloudflareaccess.com) and the Access application's AUD tag. /connect/* then requires a valid Access token, checked by the server itself.

EASYBILL_ICON_PATH

—

Path to an .svg, .png or .ico file (e.g. a file mount in your hosting platform). Served as /favicon.ico and /favicon.<ext>, linked from the pages and announced as the MCP server icon. claude.ai shows the domain's favicon next to a custom connector.

EASYBILL_CONNECT_MODE

apikey (oauth if a client ID is set)

How people connect easybill accounts.

EASYBILL_OAUTH_CLIENT_ID / _SECRET

—

OAuth mode: the client easybill issued for this server.

EASYBILL_OAUTH_ISSUER

https://api.easybill.de

OAuth mode: easybill's OAuth issuer.

EASYBILL_MCP_ACCESS_TOKEN_TTL

3600

Lifetime (s) of access tokens issued to MCP clients.

EASYBILL_MCP_REFRESH_TOKEN_TTL

7776000

Lifetime (s) of refresh tokens issued to MCP clients (90 days).

Needs Node.js ≥ 22.13 (built-in node:sqlite). The Dockerfile builds a ready image:

docker build -t easybill-mcp .
docker run -p 3000:3000 -v easybill-mcp-data:/data \
  -v $PWD/tenants.json:/config/tenants.json:ro \
  -e EASYBILL_TENANTS_FILE=/config/tenants.json \
  -e EASYBILL_PUBLIC_URL=https://easybill-mcp.example.com \
  -e EASYBILL_MCP_SECRET="$(openssl rand -base64 48)" \
  easybill-mcp

Cloudflare Zero Trust: protect only the path /connect with an Access application (the connect pages are opened in a browser). Leave /mcp, /token, /register, /authorize and /.well-known/* outside Access — claude.ai calls them from its servers and cannot pass an Access login. Without the connect pages nobody can complete the authorization, so tokens stay out of reach. Set the two EASYBILL_CF_ACCESS_* variables so the server rejects requests that bypass Cloudflare (e.g. via the origin IP).

Run it behind TLS (reverse proxy). Then in claude.ai: Settings → Connectors → Add custom connector with https://easybill-mcp.example.com/mcp (organization admins can add it once for everyone; each person still connects their own easybill logins).

Configuration

Variable

Default

Purpose

EASYBILL_API_KEY

—

Required. Your easybill API key.

EASYBILL_ENABLE_WRITES

unset

Set to true to register create/update/delete tools. Otherwise read-only.

EASYBILL_RATE_LIMIT_PER_MINUTE

60

Client-side throttle. Use 10 for Professional, 60 for Premium.

EASYBILL_CHARACTER_LIMIT

25000

Max characters per response before truncation.

EASYBILL_TIMEOUT_MS

30000

HTTP request timeout.

EASYBILL_MAX_RETRIES

3

Retries on HTTP 429 / 5xx.

EASYBILL_BASE_URL

easybill production

Override for a proxy or test double.


Tools

Customer lookup

Tool

Access

easybill_find_customer

read — start here: search customers or suppliers by name, email or number

Uses easybill's full-text search (one request, archived contacts included) and ranks the hits locally, tolerating legal forms (GmbH & Co. KG), punctuation (M.B. MUSTERMANN vs MB Mustermann), umlauts and word order. If the search endpoint is unavailable it falls back to exact filters plus a local scan of the customer list.

Documents — invoices, offers, credit notes, deliveries, orders

Tool

Access

easybill_list_documents

read

easybill_get_document

read

easybill_search_documents

read — full-text search by word, name or number

easybill_download_document

read — PDF, image, ZUGFeRD 1.0–2.5, XRechnung (to disk locally, inline when hosted)

easybill_list_document_versions

read — audit trail

easybill_create_document

write

easybill_update_document

write

easybill_complete_document

write — finalises a draft, assigns the invoice number

easybill_cancel_document

write — creates a STORNO document

easybill_convert_document

write — OFFER → INVOICE, INVOICE → DUNNING, …

easybill_send_document

write — sends real email / fax / post

easybill_delete_document

write, destructive

Customers, contacts, groups

easybill_list_customers, easybill_get_customer, easybill_create_customer, easybill_update_customer, easybill_delete_customer, easybill_list_contacts, easybill_get_contact, easybill_create_contact, easybill_update_contact, easybill_delete_contact, easybill_list_customer_groups, easybill_get_customer_group

Article catalogue and stock

easybill_list_positions, easybill_get_position, easybill_create_position, easybill_update_position, easybill_delete_position, easybill_list_stock_entries, easybill_get_stock_entry, easybill_create_stock_entry

Payments

easybill_list_document_payments, easybill_get_document_payment, easybill_create_document_payment, easybill_delete_document_payment

Projects and time tracking

easybill_list_projects, easybill_get_project, easybill_create_project, easybill_update_project, easybill_delete_project, easybill_list_time_trackings, easybill_get_time_tracking, easybill_create_time_tracking, easybill_update_time_tracking, easybill_delete_time_tracking

Attachments and templates

easybill_list_attachments, easybill_get_attachment, easybill_download_attachment, easybill_delete_attachment, easybill_list_text_templates, easybill_get_text_template, easybill_list_pdf_templates

Incoming documents (Eingangsbelege)

easybill_list_incoming_documents, easybill_search_incoming_documents, easybill_get_incoming_document, easybill_list_incoming_document_files, easybill_download_incoming_document_file (read); easybill_upload_incoming_document, easybill_update_incoming_document, easybill_complete_incoming_document, easybill_delete_incoming_document (write).

Uploads are extracted by easybill in the background; the tools guide the agent through review → correction → completion.

Server

easybill_get_server_info — reports mode, limits and whether the credentials work. In hosted mode also easybill_list_accounts — connected accounts and the link to connect more.

Files in hosted mode: downloads come back inside the tool result and uploads take base64 — the server never reads or writes caller-chosen paths on its own disk.


Things worth knowing

The server tells the agent how to sequence work

A plain set of endpoint wrappers leads agents astray. Handed an inbound customer inquiry, Claude's first instinct was to call easybill_list_documents — which cannot answer the actual first question, is this company already a customer?

The server therefore ships MCP server instructions (see src/instructions.ts) with the ordering for common tasks, and easybill_create_document opens with the same sequence:

1. easybill_find_customer     — does the customer exist?
2. easybill_create_customer   — only if not
3. easybill_create_document   — creates a DRAFT
4. review with the user
5. easybill_complete_document — assigns the official number, locks it
6. easybill_send_document     — only when explicitly asked

easybill_list_documents explicitly says it is not the tool for orienting yourself. If you extend this server, keep that pattern: state prerequisites at the top of the description of the tool an agent will reach for first.

All money is in cents

easybill represents every monetary value as an integer in cents, even where the API types it as a float. 1999 means 19.99 EUR. This is stated in every tool description that touches an amount, because getting it wrong produces invoices off by 100×.

Times in time tracking (timer_value) are in minutes.

Drafts vs. completed documents

easybill_create_document produces a draft. It has no official document number and can still be edited. Call easybill_complete_document to finalise it — easybill then assigns the number and locks it.

To void a completed invoice, use easybill_cancel_document (which creates a proper STORNO document), not easybill_delete_document. Completed invoices generally cannot be deleted for legal reasons.

Rate limits are low

easybill allows 10 requests/minute on Professional and 60 on Premium (formerly PLUS and BUSINESS). The server throttles itself to EASYBILL_RATE_LIMIT_PER_MINUTE and, if a 429 slips through, retries while honouring Retry-After. Set the variable to match your plan — otherwise a broad question that pages through many documents will stall.

Because of this, prefer narrow filters over paging: easybill_list_documents with type='INVOICE' and paid_at='null' costs one request, where scanning everything costs dozens.

Context management

Document has 69 fields and Customer 79. List tools therefore return a compact default field set, and single-record lookups return everything. Both accept fields:

  • omit it → compact defaults

  • fields: ["number", "amount"] → just those (plus id)

  • fields: ["all"] → every field

Responses over EASYBILL_CHARACTER_LIMIT are truncated, halving the item count until they fit, and say so in truncation_message.

Full-text search vs. filters

List filters match exact values (each accepts several comma-separated). For a partial name, a word or a topic use the full-text tools (API 1.102+): easybill_find_customer, easybill_search_documents, easybill_search_incoming_documents. Each costs one request.

Useful filter recipes

Question

Call

Which invoices are unpaid?

easybill_list_documents type='INVOICE', paid_at='null'

Revenue in 2025?

easybill_list_documents type='INVOICE', document_date='2025-01-01,2025-12-31'

One customer's history

easybill_list_documents customer_id=<id>

Only real, non-cancelled invoices

add is_draft='0', cancel_id='null'

Unbilled tracked time

easybill_list_time_trackings, then filter cleared_at = null


Development

npm run build      # compile to dist/
npm run typecheck  # tsc --noEmit
npm test           # offline suite — 37 tests, no credentials needed
npm run test:live  # read-only tests against a real account (needs .env)
npm run test:all   # both
npm run dev        # watch mode
npm run smoke      # read-only self-test against the live API (needs .env)
npm run inspect    # MCP Inspector against the built server (needs .env)

Tests

npm test runs offline and needs no easybill account — it covers response shaping, the HTTP client against a mock API, the rate-limit throttle, and the MCP surface (schemas, annotations, write-gating, error handling) driven over the real stdio protocol.

test/
├── helpers/mcp-client.mjs  minimal MCP stdio client + mock API server
├── format.test.mjs         field selection, pagination, truncation, markdown
├── client.test.mjs         auth headers, query serialisation, 429 retry, error mapping
├── rate-limit.test.mjs     sliding-window throttle
├── server.test.mjs         tool registration, workflow guidance, validation, errors
└── live.test.mjs           optional: read-only checks against a real account

live.test.mjs skips itself unless EASYBILL_API_KEY is set, so contributors without an account still get a green suite. It only reads — nothing in the test suite writes to easybill.

Project layout:

src/
├── index.ts              entry point, stdio transport, env validation, --selftest
├── instructions.ts       MCP server instructions: workflow ordering for the agent
├── constants.ts          config, summary field sets, enums
├── schemas/common.ts     shared Zod building blocks
├── services/
│   ├── client.ts         HTTP, auth, throttling, retries, error mapping
│   └── format.ts         field selection, pagination, markdown, truncation
└── tools/
    ├── registry.ts       registration + write-gating
    ├── crud.ts           generic CRUD tool factory
    ├── search.ts         fuzzy customer lookup
    ├── documents.ts      documents + lifecycle actions
    ├── customers.ts      customers, contacts, groups
    ├── catalog.ts        positions, stock
    ├── finance.ts        payments
    ├── work.ts           projects, time tracking
    ├── files.ts          attachments, templates
    └── meta.ts           server info

Most resources are generated from a declarative config in crud.ts; only genuinely resource-specific behaviour (document lifecycle, downloads, sending) is hand-written.

Contributing

Issues and pull requests welcome. The tool surface is derived from easybill's official OpenAPI spec (https://api.easybill.de/rest/v1/swagger.json) — when adding a tool, check field names and types against the spec rather than guessing, and mind that monetary fields are cents even where the spec types them as floats.

Disclaimer

This is an unofficial, community-maintained project. It is not affiliated with, endorsed by, or supported by easybill GmbH. "easybill" is a trademark of its respective owner and is used here only to describe what this software talks to.

The software is provided as-is under the MIT license, without warranty. It can create, modify and delete records in your accounting system, and can send invoices to your customers. You are responsible for what you let it do — start read-only, and review what write tools produce before relying on it.

License

MIT © stack74

Available Tools

28 tools
easybill_download_attachmentDownload attachmentA
Read-onlyIdempotent

Download an attachment's file content and save it to a local path.

Returns the saved file path and size in bytes. The content is NOT loaded into the conversation, so this is safe for large files. Find attachment IDs with easybill_list_attachments.

Inputs: id (required), output_path (required).

easybill_download_documentDownload document fileA
Read-onlyIdempotent

Download a document as a PDF or e-invoicing file and save it to a local path.

Supported formats: 'pdf' (plain), 'zugferd1', 'zugferd2_2' (PDF with embedded XML), 'xrechnung2_3', 'xrechnung3_0' (XML), and 'jpg' (first page as an image).

Returns the saved file path and its size in bytes. The file content itself is NOT loaded into the conversation, so this is safe for large PDFs.

Inputs: id (required), output_path (required), format.

easybill_find_customerFind a customer by name, email or number (fuzzy)A
Read-onlyIdempotent

Search for an existing customer by company name, person name, email, customer number or city.

USE THIS FIRST whenever you need to know whether someone is already a customer — for example before creating an offer or invoice from an inbound inquiry. The easybill API has no full-text search, so this tool combines exact filters with a local fuzzy match over the customer list.

It tolerates the differences that break exact matching: legal forms ('GmbH & Co. KG'), punctuation ('M.B. MUSTERMANN' vs 'MB Mustermann'), umlauts, and word order.

Args:

  • query (string): what to search for. A company name, surname, email or customer number.

  • limit (number): max candidates to return, 1-25 (default 5).

  • min_score (number): 0-1 match threshold (default 0.5). Lower it to cast a wider net.

  • max_pages (number): how many pages of 1000 customers to scan in the fallback (default 3). Each page is one API request, so keep this low on a plan with a 10 req/min limit.

Returns: { query, match_count, exact_match (boolean), candidates[] } where each candidate has its easybill 'id', 'match_score' (1 = certain) and the usual summary fields.

Next steps based on the result:

  • Exactly one strong candidate (score 1) -> use its 'id' as customer_id.

  • Several candidates -> show them to the user and ask which one, do NOT guess.

  • No candidates -> the customer does not exist yet. Create it with easybill_create_customer, then use the returned 'id'.

Examples:

  • "Is Mustermann Handels GmbH & Co. KG already a customer?" -> query="Mustermann Handels GmbH & Co. KG"

  • "Find the customer with email einkauf@example.com" -> query="einkauf@example.com"

  • "Look up customer number 10023" -> query="10023"

Inputs: query (required), limit, max_pages, min_score, +1 more.

easybill_get_attachmentGet attachmentA
Read-onlyIdempotent

Fetch one attachment by its numeric easybill ID, returning all fields by default.

Use easybill_list_attachments first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), fields, response_format.

easybill_get_contactGet contactA
Read-onlyIdempotent

Fetch one contact by its numeric easybill ID, returning all fields by default.

Use easybill_list_contacts first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), customer_id (required), fields, response_format.

easybill_get_customerGet customerA
Read-onlyIdempotent

Fetch one customer by its numeric easybill ID, returning all fields by default.

Use easybill_list_customers first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), fields, response_format.

easybill_get_customer_groupGet customer groupA
Read-onlyIdempotent

Fetch one customer group by its numeric easybill ID, returning all fields by default.

Use easybill_list_customer_groups first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), fields, response_format.

easybill_get_documentGet documentA
Read-onlyIdempotent

Fetch one document by its numeric easybill ID, returning all fields by default.

Use easybill_list_documents first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), fields, response_format.

easybill_get_document_paymentGet document paymentA
Read-onlyIdempotent

Fetch one document payment by its numeric easybill ID, returning all fields by default.

Use easybill_list_document_payments first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), fields, response_format.

easybill_get_positionGet positionA
Read-onlyIdempotent

Fetch one position by its numeric easybill ID, returning all fields by default.

Use easybill_list_positions first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), fields, response_format.

easybill_get_projectGet projectA
Read-onlyIdempotent

Fetch one project by its numeric easybill ID, returning all fields by default.

Use easybill_list_projects first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), fields, response_format.

easybill_get_server_infoGet server info and connection statusA
Read-onlyIdempotent

Report this MCP server's configuration and verify the easybill API credentials work.

Call this when a write tool appears to be missing, when you get authentication errors, or when you hit rate limits — it explains the current mode and limits.

Returns: { server_version, api_base_url, writes_enabled, tools_registered, rate_limit_per_minute, character_limit, connection } where 'connection' reports whether a live test call to easybill succeeded.

Inputs: test_connection.

easybill_get_stock_entryGet stock entryA
Read-onlyIdempotent

Fetch one stock entry by its numeric easybill ID, returning all fields by default.

Use easybill_list_stock_entries first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), fields, response_format.

easybill_get_text_templateGet text templateA
Read-onlyIdempotent

Fetch one text template by its numeric easybill ID, returning all fields by default.

Use easybill_list_text_templates first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), fields, response_format.

easybill_get_time_trackingGet time tracking entryA
Read-onlyIdempotent

Fetch one time tracking entry by its numeric easybill ID, returning all fields by default.

Use easybill_list_time_trackings first if you only know a name or number. Pass 'fields' to narrow the response. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: id (required), fields, response_format.

easybill_list_attachmentsList attachmentsA
Read-onlyIdempotent

List attachments from easybill with optional filters and pagination.

Files stored in easybill and linked to a document, customer or project. This endpoint has no filters — page through the list and match on 'document_id', 'customer_id' or 'file_name'. Use easybill_download_attachment to fetch the actual file content.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: page, limit, fields, response_format.

easybill_list_contactsList contactsA
Read-onlyIdempotent

List contacts from easybill with optional filters and pagination.

Contacts are always scoped to one customer, so 'customer_id' is required.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: customer_id (required), page, limit, fields, +1 more.

easybill_list_customer_groupsList customer groupsA
Read-onlyIdempotent

List customer groups from easybill with optional filters and pagination.

Customer groups classify customers and can carry their own pricing level. Use a group's 'id' as 'group_id' when creating or filtering customers.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: page, limit, fields, response_format.

easybill_list_customersList customersA
Read-onlyIdempotent

List customers from easybill with optional filters and pagination.

NOTE: easybill has no fuzzy full-text customer search. The filters below match exact values (though each accepts several comma-separated values). To find a customer by a partial name, filter on company_name or last_name with the exact spelling, or page through the list and match locally.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: page, limit, emails, fields, +10 more.

easybill_list_document_paymentsList document paymentsA
Read-onlyIdempotent

List document payments from easybill with optional filters and pagination.

Payments booked against documents. Recording a payment is what marks an invoice as paid — it updates the document's 'paid_amount' and 'paid_at'. To find open invoices instead, use easybill_list_documents with type='INVOICE' and paid_at='null'. Amounts are integers in cents (150 = 1.50 EUR).

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: page, limit, fields, reference, +3 more.

easybill_list_documentsList documentsA
Read-onlyIdempotent

List documents from easybill with optional filters and pagination.

Covers every document type: invoices, offers, credit notes, reminders, deliveries, orders.

NOT the right tool for: finding out whether a customer exists (use easybill_find_customer), or orienting yourself before creating a document (see easybill_create_document). Only call this when you actually need to read existing documents, and always with a filter.

Common recipes:

  • Unpaid invoices: type='INVOICE', paid_at='null'

  • Revenue in a period: type='INVOICE', document_date='2025-01-01,2025-12-31'

  • A customer's history: customer_id=

  • Exclude drafts: is_draft='0' - exclude cancelled: cancel_id='null'

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: page, type, limit, title, +16 more.

easybill_list_document_versionsList document versionsA
Read-onlyIdempotent

List the change history of a document. easybill snapshots a version whenever a completed document is modified, which is what you need for audit questions like 'was this invoice altered after it was issued?'.

Returns: { total, count, page, pages, items[] } with each version's id, created_at and reason.

Inputs: id (required), page, limit, response_format.

easybill_list_pdf_templatesList PDF templatesA
Read-onlyIdempotent

List the PDF layout templates configured in your easybill account.

Pass a template's 'id' as 'pdf_template' when creating or converting a document to control its layout and language. The built-in values are 'DE' (German, the default) and 'EN' (English); anything custom uses a numeric ID.

Note: this endpoint is not paginated and returns all templates at once.

Inputs: type, response_format.

easybill_list_positionsList positionsA
Read-onlyIdempotent

List positions from easybill with optional filters and pagination.

Positions are the reusable article catalogue (products, services and text blocks). Referencing one by 'position_id' in a document line item copies its price and description over. Prices are integers in cents (1999 = 19.99 EUR).

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: page, type, limit, fields, +2 more.

easybill_list_projectsList projectsA
Read-onlyIdempotent

List projects from easybill with optional filters and pagination.

Projects group documents and tracked time under a customer engagement, with an optional budget. 'consumed_amount' and 'consumed_time' show progress against 'budget_amount' and 'budget_time' — useful for budget-burn questions. Amounts are integers in cents; times are in minutes.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: page, limit, fields, status, +2 more.

easybill_list_stock_entriesList stock entriesA
Read-onlyIdempotent

List stock entries from easybill with optional filters and pagination.

Stock entries are the inventory movement log for articles that have stock management enabled (position.stock = 'YES'). Each entry records a new absolute stock level. Filter by position_id to see one article's history.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: page, limit, fields, document_id, +2 more.

easybill_list_text_templatesList text templatesA
Read-onlyIdempotent

List text templates from easybill with optional filters and pagination.

Reusable text blocks for document headers, footers and notes. Handy for reusing your standard payment terms or closing wording when creating a document.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: page, limit, fields, response_format.

easybill_list_time_trackingsList time tracking entriesA
Read-onlyIdempotent

List time tracking entries from easybill with optional filters and pagination.

Tracked working time, optionally tied to a project and an article. 'timer_value' is the tracked duration in MINUTES and 'hourly_rate' is in cents. 'cleared_at' is set once the entry has been billed — entries with cleared_at = null are still unbilled, which is what you want when preparing an invoice.

Returns a compact field set by default; pass 'fields' for specific columns or ['all'] for everything.

Returns: { total, count, page, pages, has_more, next_page, items[] }. Use 'next_page' to continue paging. Monetary values are integers in cents (150 = 1.50 EUR).

Inputs: page, limit, fields, login_id, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 28 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action, with clear list/get/action naming. The only potential overlap between find_customer and list_customers is clearly resolved in the descriptions: find is for fuzzy search, list is for exact filtering. Downloads for documents and attachments are unambiguous.

    Naming Consistency5/5

    All tools follow the easybill_<verb>_<noun> pattern consistently, using list/get/download/find as verbs. Even get_server_info fits the get_ pattern. No mixed conventions or vague verbs.

    Tool Count3/5

    With 28 tools, the count exceeds the comfortable range, but it is justifiable given the many distinct resources (customers, documents, projects, etc.) covered by the easybill API. It borders on heavy, but each tool has a clear purpose.

    Completeness2/5

    The server is read-only but repeatedly references missing write tools like easybill_create_customer and easybill_create_document, creating dead ends for agents. There are no create, update, or delete operations, which is a significant gap for an ERP integration.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      MCP server for the DataGate billing platform API, providing read-only tools to manage customers, invoices, products, agreements, sites, and payments.
      13
      24 PyPI
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for the Billingo V3 Hungarian invoicing API. Manage invoices, partners, products, spendings, and bank accounts from any MCP client.
      14 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for the Invapi E-Invoicing API, enabling conversion, validation, and extraction of invoices in UBL, CII, ZUGFeRD, Excel, and more.
      40 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      An MCP server for the SmartBill Cloud API. It lets an MCP client issue and manage Romanian invoices, proformas and payments, download document PDFs, and read VAT rates, series and stock levels.
      23
      2
      MIT