easybill-mcp
Read-only easybill MCP server for finding and retrieving accounting data across customers, documents, catalog, payments, projects, time tracking, attachments, and templates.
Fuzzy-search customers by name, email, customer number, or city, and list/get contacts and customer groups.
List/get documents such as invoices, offers, credit notes, orders, and reminders; download PDFs/e-invoices; inspect document version history.
Browse reusable article positions and stock entries.
List/get document payments.
List/get projects and time-tracking entries, including unbilled tracked time.
List/get/download attachments and read text/PDF templates.
Check server mode, limits, and whether easybill credentials are working.
Use filters, pagination, field selection, and markdown/JSON responses to keep context small.
When writes are explicitly enabled, additional create/update/delete and document lifecycle tools (draft, complete, cancel, convert, send) become available.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@easybill-mcp Show me the latest unpaid invoices"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpConfiguration is entirely through environment variables (full list under Configuration). Two matter now:
Leave
EASYBILL_ENABLE_WRITESunset to start read-only.Set
EASYBILL_RATE_LIMIT_PER_MINUTEto 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 |
Cursor |
|
Windsurf |
|
Cline / Roo Code | MCP Servers panel → Configure MCP Servers ( |
Gemini CLI |
|
Claude Code |
|
VS Code / Copilot |
|
Zed |
|
Codex CLI |
|
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-mcpclaude 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-mcpThe 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 buildThen 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-mcpTest 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 smokeIt 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 .envNote:
.envis 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 defaultVerify 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:
Someone adds the connector in claude.ai (or any OAuth-capable MCP client).
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.
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 |
| Slug the model passes as |
| Shown on the connect page and to the model. |
|
|
|
|
| Optional override of the easybill OAuth scopes. |
| OAuth mode only: |
Environment
Variable | Default | Purpose |
| — | Required. Public https base URL. The connector URL is |
| — | Required. ≥ 32 characters; encrypts stored tokens and signs the browser cookie. Changing it invalidates all connections. |
| — | Required. Path to the tenant JSON, or the JSON inline. |
|
| SQLite file. Put it on a persistent volume. |
|
| Listen address. |
| — | Put the connect pages behind Cloudflare Access: team domain (e.g. |
| — | Path to an |
|
| How people connect easybill accounts. |
| — | OAuth mode: the client easybill issued for this server. |
|
| OAuth mode: easybill's OAuth issuer. |
|
| Lifetime (s) of access tokens issued to MCP clients. |
|
| 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-mcpCloudflare 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 |
| — | Required. Your easybill API key. |
| unset | Set to |
|
| Client-side throttle. Use |
|
| Max characters per response before truncation. |
|
| HTTP request timeout. |
|
| Retries on HTTP 429 / 5xx. |
| easybill production | Override for a proxy or test double. |
Tools
Customer lookup
Tool | Access |
| 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 |
| read |
| read |
| read — full-text search by word, name or number |
| read — PDF, image, ZUGFeRD 1.0–2.5, XRechnung (to disk locally, inline when hosted) |
| read — audit trail |
| write |
| write |
| write — finalises a draft, assigns the invoice number |
| write — creates a STORNO document |
| write — OFFER → INVOICE, INVOICE → DUNNING, … |
| write — sends real email / fax / post |
| 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 askedeasybill_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 (plusid)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? |
|
Revenue in 2025? |
|
One customer's history |
|
Only real, non-cancelled invoices | add |
Unbilled tracked time |
|
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 accountlive.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 infoMost 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 toolseasybill_download_attachmentDownload attachmentARead-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 fileARead-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)ARead-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 attachmentARead-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 contactARead-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 customerARead-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 groupARead-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 documentARead-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 paymentARead-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 positionARead-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 projectARead-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 statusARead-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 entryARead-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 templateARead-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 entryARead-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 attachmentsARead-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 contactsARead-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 groupsARead-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 customersARead-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 paymentsARead-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 documentsARead-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 versionsARead-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 templatesARead-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 positionsARead-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 projectsARead-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 entriesARead-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 templatesARead-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 entriesARead-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
Scored across 28 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for ABRA Flexi — accounting, contacts, stock and draft-checked invoice creation.
MCP server for MOCO business software: time tracking, projects, budgets, and invoicing via API
Free hosted MCP for invoices, estimates, clients, items and PDFs. OAuth authorization required.
Hosted MCP server for OTTO Market, Kaufland and Mirakl sellers: orders, stock, listings and ads.
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server for the DataGate billing platform API, providing read-only tools to manage customers, invoices, products, agreements, sites, and payments.1324 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceMCP server for the Billingo V3 Hungarian invoicing API. Manage invoices, partners, products, spendings, and bank accounts from any MCP client.14 npm1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for the Invapi E-Invoicing API, enabling conversion, validation, and extraction of invoices in UBL, CII, ZUGFeRD, Excel, and more.40 npmMIT
- AlicenseAqualityCmaintenanceAn 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.232MIT