Toconline

Unofficial. This is an independent, community-built project. It is not affiliated with, endorsed by, or supported by TOCOnline or Cloudware S.A. "TOCOnline" is a trademark of its respective owner. Use at your own risk — see the warranty disclaimer.

Local MCP server wrapping the TOCOnline accounting/invoicing API. Lets AI assistants list customers, look up products, draft sales documents, and call arbitrary TOCOnline endpoints on your behalf — after a one-time OAuth login.

Quick start

The whole setup is four steps. Each links to its full section below.

1. Install the launcher (needs Python 3.11+ and uv):

   git clone https://github.com/themiguelamador/toconline-mcp.git
   cd toconline-mcp && uv tool install --from . toconline-mcp
   

   → puts a toconline-mcp launcher on your PATH. Details.

2. Get your TOCOnline API credentials — in the TOCOnline web app, Empresa → Configurações → Dados API, request access and set the redirect URL to http://127.0.0.1:53682/callback. You'll end up with five values (client_id, client_secret, two OAuth URLs, an API URL). Details.

3. Register the server with your client — one line for Claude Code, a small JSON block for Claude Desktop. Details.

4. Log in — ask your assistant "Log in to TOCOnline" (paste the five values), or run toconline-mcp setup. A browser opens, you approve, done. Details.

That's it — read-only use works on any plan. Creating/editing documents needs an active GC license. Gmail is a separate, optional add-on for archiving invoice PDFs from email — skip it unless you want it (details).

Status

Alpha. Covers the most common read and write operations for customers, suppliers, products, and commercial sales documents, plus a generic api_request escape hatch.

Prerequisites

• macOS or Linux (Windows untested).
• Python 3.11+.
• A TOCOnline account with admin access and, for anything beyond GET requests, an active GC (Gestão Comercial) license. GET-only use works on any plan.
• An API integration configured in TOCOnline — see Getting TOCOnline API credentials below.
• uv (recommended) or pipx or plain python3 -m venv.

Install

Not yet published to PyPI — install from source:

git clone https://github.com/themiguelamador/toconline-mcp.git
cd toconline-mcp

# Recommended: uv
uv tool install --from . toconline-mcp
# → installs to ~/.local/share/uv/tools/toconline-mcp/
# → launcher at /Users/<you>/.local/bin/toconline-mcp

# Or pipx
pipx install .

# Or vanilla Python
python3 -m venv ~/.local/toconline-mcp
~/.local/toconline-mcp/bin/pip install .

macOS sandbox note. Claude Desktop is sandboxed and cannot execute binaries whose Python installation lives under ~/Documents/, ~/Desktop/, or ~/Downloads/. The server will fail to start with PermissionError: … /.venv/pyvenv.cfg. Always install via one of the methods above — they all land outside the TCC-protected folders. Do not point Claude Desktop at a .venv/bin/toconline-mcp that lives inside your cloned repo if the repo sits in ~/Documents/.

Updating after code changes

When you pull new commits or edit the source, three steps — and which you need depends on what changed:

# 1. Rebuild the installed launcher (always)
uv tool install --from . toconline-mcp --reinstall

2. Restart the server — fully quit the client (Claude Desktop: ⌘Q, not just the window) and reopen, or kill the running toconline-mcp process so it respawns with the new code.
3. Start a new chat — only needed when you added or renamed a tool. The chat caches the tool list it got at startup, so a new tool won't appear in an existing conversation even after the server restarts.

Editing an existing tool's behaviour needs only steps 1–2; adding or renaming a tool needs all three. See Iteration workflow for the full explanation and how to find/kill stale processes.

Getting TOCOnline API credentials

Based on the official TOCOnline API docs. These steps are one-time per company/tenant.

1. Request API access

In the TOCOnline web app, go to Empresa → Configurações → Dados API (Company → Settings → API Data). Fill in the integrator details (company info + contact email) and submit.

TOCOnline will email the integrator address a temporary link (valid ~72h) where you can view and edit the API credentials and integration settings.

2. Read the values off the email link page

The link page shows five values you will need:

TOCOnline variable	What it is	Use in this MCP
OAUTH_CLIENT_ID	OAuth client id	client_id
OAUTH_CLIENT_SECRET	OAuth client secret	client_secret
OAUTH_URL	Your tenant's OAuth base URL	auth_url = <OAUTH_URL>/auth, token_url = <OAUTH_URL>/token
API_URL	Your tenant's API base URL	api_base
OAUTH_REDIRECT_URL	Callback URL (pre-set by TOCOnline; editable)	must match what this MCP uses — see next step

The OAUTH_URL / API_URL values are tenant-specific. Use the exact values shown on the email link page — the default api_base baked into this tool (https://apiv1.toconline.com) is a generic placeholder and may not match your tenant.

3. Set the redirect URL to match this MCP

This is the single step most people get wrong. TOCOnline pre-fills OAUTH_REDIRECT_URL with something like http://127.0.0.1:4080/oauth/callback. This MCP expects http://127.0.0.1:53682/callback (different port, different path).

On the email link page (or later, back in Empresa → Configurações → Dados API), overwrite OAUTH_REDIRECT_URL with exactly:

http://127.0.0.1:53682/callback

Save. That's it.

If port 53682 is taken on your machine, pick any free port and pass it as redirect_port to the login tool (or --port N to the CLI). The path must remain /callback.

4. Log in

Two equivalent ways — pick whichever fits your workflow.

A. From inside your AI client (recommended)

After registering the server with Claude, ask:

Log in to TOCOnline. Here are the values from Empresa → Configurações → Dados API: client_id = ..., client_secret = ..., auth_url = <OAUTH_URL>/auth, token_url = <OAUTH_URL>/token, api_base = <API_URL>.

Claude invokes the login tool, your browser opens to TOCOnline consent, you approve, and credentials land in ~/.config/toconline-mcp/credentials.json (mode 0600). No separate terminal step.

Any time later, ask Claude to run auth_status to see whether credentials are configured and how long until the access token expires, or logout to clear them.

B. From the command line

toconline-mcp setup

Prompts for each value interactively, opens the browser, writes the credentials file. You can also set them in the environment first to skip the prompts:

export TOCONLINE_CLIENT_ID='...'
export TOCONLINE_CLIENT_SECRET='...'
export TOCONLINE_AUTH_URL='<OAUTH_URL>/auth'
export TOCONLINE_TOKEN_URL='<OAUTH_URL>/token'
export TOCONLINE_API_BASE='<API_URL>'
toconline-mcp setup

If the MCP server is already running in your client, restart/reconnect it afterwards — it caches credentials in memory at startup, so auth_status will show the fresh token while real calls still fail with unauthorized_client until the server reloads the file.

Token lifetime

Per TOCOnline's auth docs, the access token lasts 4 hours (expires_in: 14400) and the refresh token 8 hours. This MCP refreshes the access token automatically (2 minutes before expiry) whenever you make a request, so during active use you never notice.

The catch is the 8-hour refresh window: if the server sits idle for more than 8 hours, the refresh token expires and the next call fails with a 401 — you'll need to re-run login / setup. (This is a TOCOnline limit, not something this MCP can extend.) You also re-login if you revoke the integration, rotate the client secret, or change OAUTH_REDIRECT_URL.

Register with Claude

Both clients need the absolute path to the installed launcher. Find yours with:

which toconline-mcp
# → e.g. /Users/<you>/.local/bin/toconline-mcp

Claude Code

claude mcp add toconline -- /Users/<you>/.local/bin/toconline-mcp

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add the toconline entry under mcpServers:

{
  "mcpServers": {
    "toconline": {
      "command": "/Users/<you>/.local/bin/toconline-mcp"
    }
  }
}

Fully quit Claude Desktop (⌘Q — closing the window is not enough) and reopen it. toconline should now appear in your connectors list with a DESKTOP badge.

If the server doesn't show up

Check the log:

tail -50 ~/Library/Logs/Claude/mcp-server-toconline.log

Two common errors:

• PermissionError: … /.venv/pyvenv.cfg — sandbox blocked the venv. Install via uv tool install --from . toconline-mcp (see above) and point the config at ~/.local/bin/toconline-mcp, not a .venv under ~/Documents/.
• ENOENT / command not found — the path in the config is wrong. Run which toconline-mcp again and paste that exact path into the config.

Once this package is published to PyPI

After a uv publish, the config can use the shorter portable form that doesn't depend on a specific user's filesystem:

{
  "mcpServers": {
    "toconline": { "command": "uvx", "args": ["toconline-mcp"] }
  }
}

API coverage

Targets the TOCOnline Open API v1.0.0 (JSON:API), documented at api-docs.toconline.pt with the full OpenAPI 3.0.3 spec on SwaggerHub (68 paths). The base URL is region-specific — e.g. https://api14.toconline.pt (the digits match your account's region). A few document actions (finalize, email) use TOCOnline's legacy v1 action endpoints, which aren't in the public docs but ship in the Postman collection from Empresa → Configurações → Dados API.

Mapped against the public docs — ✅ typed tool, ⚠️ partial, ❌ api_request only:

API section (docs)	Resource	Coverage
Empresa	Clientes (+ morada, e-mail)	✅ full CRUD + addresses/contacts
Empresa	Fornecedores (+ morada, e-mail)	✅ full CRUD + addresses/contacts
Empresa	Produtos e Serviços	✅ full CRUD
Vendas	Documentos de Venda	✅ list/get/create/delete
Vendas	Recibos de Venda	✅ list/get/create + void
Vendas	PDF (documento + recibo)	✅ get_document_pdf_url
Vendas	Envio por e-mail	✅ send_document_email
Vendas	Comunicação à AT	✅ communicate_sales_document_at
Compras	Documentos de Compra	✅ list/get/create + finalize/void
Compras	Pagamentos	✅ list/get/create
Compras	PDF / Comunicação à AT	✅ pdf url + communicate_purchase_document_at
Auxiliares	Descritores de Taxa	✅ list_tax_descriptors
Auxiliares	Família de Itens	✅ list_item_families
Auxiliares	Países	✅ list_countries
Auxiliares	Unidades de Medida	✅ list_units_of_measure
Auxiliares	Contas Bancárias	✅ list_bank_accounts / get
Auxiliares	Caixa Associada	✅ list_cash_accounts
Auxiliares	Unidade Monetária (moedas)	❌ api_request
Auxiliares	Taxas (tax rates)	❌ api_request
Auxiliares	Categorias de Despesa	❌ api_request
Auxiliares	Documentos de Série	❌ api_request
Auxiliares	OSS (países e taxas)	❌ api_request
Vendas/Compras	Settlement / payment lines	✅ create_sales_receipt_line / create_purchase_payment_line

Anything ❌ works today through api_request with no new code — the four uncovered auxiliary tables are read-only lookups. Ask if you want any promoted to a typed tool.

Validation status

How far each recently added/changed tool has been verified — live = a real call against the API succeeded; unit = payload shape covered by tests but not run against the API; untested = no automated or live check yet.

Tool(s)	Status
list_countries, list_item_families, list_units_of_measure, list_tax_descriptors, list_cash_accounts	✅ live
create_product (incl. required type + item_family_id)	✅ live
delete_product	✅ live
create_service, delete_service	✅ live
update_product, update_service	🧪 unit
create_customer / update_customer / delete_customer	🧪 unit
create_supplier / update_supplier / delete_supplier	🧪 unit
create_sales_receipt_line, create_purchase_payment_line	🧪 unit — money path, not run live (settles real documents)
communicate_sales_document_at, communicate_purchase_document_at	⏳ untested — binding AT submission

Tools

54 typed tools plus a generic escape hatch. The typed tools expose exact-match filters only, but the underlying API supports comparison operators — e.g. filter="documents.pending_total>0" or document_lines.created_at>'2022-01-01'::date. Reach for api_request with a raw filter param when you need ranges or date comparisons.

Authentication

Tool	Purpose
auth_status	Check whether credentials are configured and when the access token expires.
login	Run the OAuth browser flow and store credentials.
logout	Delete stored credentials.

Customers, suppliers, products

Tool	Purpose
list_customers / get_customer / create_customer / update_customer / delete_customer	Customer CRUD.
list_suppliers / get_supplier / create_supplier / update_supplier / delete_supplier	Supplier CRUD.
list_products / get_product / create_product / update_product / delete_product	Product CRUD.
list_services / get_service / create_service / update_service / delete_service	Service CRUD.

delete_* require confirm=true. Create/update set the API-required item type attribute (Product/Service) automatically.

Reference tables (read-only)

Lookup resources used when building documents and items.

Tool	Purpose
list_countries	ISO country codes and names.
list_item_families	Item families for categorizing products/services (item_family_id).
list_units_of_measure	Units (unidades) for document lines.
list_tax_descriptors	VAT rates and their codes (NOR, INT, RED, ISE).
list_cash_accounts	Cash accounts (caixas) for receipts/payments.
list_document_series	Document series (séries) per type — prefix, numbering, is_default. Pass a series id as series_id to create_sales_document.

Addresses & contacts

Addresses and contacts are separate JSON:API resources with an owning customer_id or supplier_id (exactly one, not both).

Tool	Purpose
list_addresses / get_address / create_address / update_address / delete_address	Address CRUD. Scope listings by customer_id or supplier_id.
list_contacts / get_contact / create_contact / update_contact / delete_contact	Contact CRUD with the same scoping.

delete_address / delete_contact require confirm=true.

Sales documents & receipts

Tool	Purpose
list_sales_documents	Filter by document_type / customer_id / date.
get_sales_document	Single document, with its line items merged by default.
create_sales_document	Draft document with line items. For credit/debit notes, set document_type='NC' or 'ND' and pass parent_document_id to reference the original.
list_sales_receipts / get_sales_receipt / create_sales_receipt	Customer-payment receipts.
create_sales_receipt_line	Settle a sales document against a receipt (settlement line).

Purchases

Tool	Purpose
list_purchase_documents / get_purchase_document / create_purchase_document	Supplier invoices.
list_purchase_payments / get_purchase_payment / create_purchase_payment	Supplier payments.
create_purchase_payment_line	Settle a purchase document line against a payment (settlement line).

Escape hatch

Tool	Purpose
api_request	Generic /api/* passthrough for endpoints without typed tools. POST/PATCH/PUT/DELETE require confirm=true.

Listing a parent's children: some collections can't be filtered flat — GET /api/commercial_sales_document_lines?filter[document_id]=… and /api/addresses?filter[customer_id]=… both return JA011. Use the nested route instead: /api/commercial_sales_documents/{id}/lines, /api/customers/{id}/addresses. The typed tools already do this.

Response shape

Responses are flattened from JSON:API — data.attributes.* fields are hoisted to the top level, and relationships.<name>.data.id becomes <name>_id:

{
  "items": [
    {"id": "1", "type": "customers", "business_name": "ACME", "country_code": "PT"}
  ],
  "meta": {"total": 1}
}

Document actions (PDF, email, finalize, void, AT)

Tool	Purpose
get_document_pdf_url	Get a signed public URL to the PDF of a sales document, sales receipt, or purchase document. The URL works unauthenticated for a short time — share it with a user and they can download.
send_document_email	Email a sales document or receipt to a recipient via TOCOnline's mail servers.
finalize_sales_document / finalize_purchase_document	Issue a draft document. Irreversible — requires confirm=true.
void_sales_receipt / void_purchase_document	Void (anular) a document. Irreversible — requires confirm=true.
communicate_sales_document_at / communicate_purchase_document_at	Report a finalized document to the AT (tax authority). Binding — requires confirm=true.

These endpoints aren't in the public API docs but are discoverable via the Postman collection TOCOnline provides from Empresa → Configurações → Dados API.

Settlement linking

create_sales_receipt_line / create_purchase_payment_line attach a receipt or payment to the document it settles (so the document is marked paid). The two are asymmetric, per the API:

• Sales settle a whole document: receivable_type="Document", receivable_id = the sales document id.
• Purchases settle a document line: payable_type="Purchases::DocumentLine", payable_id = a purchase document line id (not the document id).

The tools build the documented payload; the settlement amounts (received_value / paid_value, settlement_amount, retention_total, …) are the caller's responsibility.

The four uncovered auxiliary read tables (currencies, taxes, expense categories, document series, OSS) stay on api_request — ask and we'll promote any to a typed tool.

Gmail integration (optional)

Most people don't need this. It's a separate add-on for one workflow: pulling supplier-invoice PDFs out of email and archiving them into a folder (local or Google-Drive/iCloud-synced), so you can then enter them in TOCOnline. It's invoice-archiving only — not a general Gmail client (no send, no delete). Completely independent of the TOCOnline tools.

Off by default — nothing to do if you don't want it. The 10 gmail_* tools only appear once Gmail credentials exist (or you set TOCONLINE_GMAIL=1). If you do want it, the three steps are below:

1. One-time Google Cloud setup — create an OAuth client (you bring your own Google credentials).
2. Log in once via the CLI — toconline-mcp gmail-setup.
3. Restart your client — the gmail_* tools now show up.

One-time Google Cloud setup

1. Go to https://console.cloud.google.com/ and create (or pick) a project.
2. APIs & Services → Library → enable Gmail API.
3. APIs & Services → OAuth consent screen → set up a "Desktop"/"External" consent screen with your email as a test user.
4. APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app (or Web app). Register http://127.0.0.1:53683/callback as an Authorized redirect URI.
5. Copy the Client ID and Client secret.

Log in

First login must use the CLI (the in-Claude gmail_* tools don't exist until credentials are present):

toconline-mcp gmail-setup

Tokens are saved to ~/.config/toconline-mcp/gmail-credentials.json (0600), separate from the TOCOnline credentials. Restart your client afterwards — the gmail_* tools (including gmail_login for re-auth) now appear.

Scope

gmail.modify — covers reading messages, downloading attachments, and adding/removing labels. It does not allow permanent deletion or sending messages. Narrower scopes (like gmail.readonly or gmail.labels) can't label messages, which breaks the "mark as imported" workflow.

Gmail tools (10)

Tool	Purpose
gmail_auth_status / gmail_login / gmail_logout	Auth lifecycle (mirrors TOCOnline's auth trio).
gmail_search_messages	Search with Gmail query syntax (has:attachment filename:pdf from:billing@…). Returns compact metadata + attachment list per message.
gmail_get_message	Fetch a single message's metadata + attachment list.
gmail_download_attachment	Download one attachment to an absolute local path. Handles filename collisions with (2), (3)… suffixes.
gmail_list_labels / gmail_create_label	Discover and create labels.
gmail_add_label_to_message / gmail_remove_label_from_message	Mark messages as processed (e.g. apply an Imported/TOCOnline label).

Example workflow: bulk-download supplier invoices

Ask Claude:

Search my Gmail for unread messages from billing@ senders with PDF attachments since 2026-04-01. For each one, download every PDF to /Users/me/Google Drive/Invoices/2026-04/ and apply the label Imported/TOCOnline. Then print a summary table.

Claude uses: gmail_search_messages → gmail_list_labels (or gmail_create_label if missing) → for each result gmail_download_attachment + gmail_add_label_to_message. Using a Google-Drive-synced folder for save_dir gives you cloud sync for free.

Gmail env vars

• TOCONLINE_GMAIL_CREDENTIALS_PATH — override the credentials file location.
• GMAIL_CLIENT_ID / GMAIL_CLIENT_SECRET — skip the CLI prompts during gmail-setup.

Config file (~/.config/toconline-mcp/.env)

Rather than exporting env vars in your shell every time, drop them in a .env file and the MCP loads it at startup. Values from real environment variables always win — the file is a fallback.

Loader checks these paths in order (first existing one wins):

1. Whatever TOCONLINE_ENV_FILE points at (if set).
2. ~/.config/toconline-mcp/.env — primary location (next to credentials.json).
3. ./.env in the current working directory (dev convenience).

Example file — all fields optional, include only what you want cached:

# ~/.config/toconline-mcp/.env

# --- TOCOnline ---
TOCONLINE_CLIENT_ID=ptNNNNNNNNN_cNNNNNN-xxxxxxxxxxxxxxxx
TOCONLINE_CLIENT_SECRET=your-rotated-secret
TOCONLINE_AUTH_URL=https://app14.toconline.pt/oauth/auth
TOCONLINE_TOKEN_URL=https://app14.toconline.pt/oauth/token
TOCONLINE_API_BASE=https://api14.toconline.pt

# --- Gmail (Google OAuth client from console.cloud.google.com) ---
GMAIL_CLIENT_ID=1234...apps.googleusercontent.com
GMAIL_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxx

Format:

• KEY=VALUE per line.
• # comments and blank lines are fine.
• Quote values with spaces: NAME="with spaces".
• export KEY=VALUE is accepted (for shell-compatibility).
• No variable interpolation ($VAR / ${VAR}) — export from shell if you need that.

After creating the file, toconline-mcp setup and toconline-mcp gmail-setup skip the interactive prompts for any field the file already provides.

Permissions: the file contains OAuth client secrets, which are less sensitive than access tokens but still not public. Chmod it:

chmod 600 ~/.config/toconline-mcp/.env

The MCP prints a warning: on stderr if it detects looser permissions.

Development

uv venv --python 3.11
uv pip install -e '.[dev]'
pytest

Environment variables:

• TOCONLINE_CREDENTIALS_PATH — override the credentials file location.
• TOCONLINE_LOG_LEVEL — DEBUG, INFO, WARNING, etc. Logs go to stderr.

Iteration workflow (picking up code changes)

uv tool install --reinstall updates the binary on disk, but does not restart already-running MCP processes — Python imports modules at startup, so a live server keeps serving the old code until killed. After editing the source:

# 1. Run the test suite (catches regressions before they hit the live server)
pytest

# 2. Refresh the installed launcher
uv tool install --from . toconline-mcp --reinstall

# 3. Find Claude Desktop's MCP server process and kill it
ps aux | grep toconline-mcp | grep -v grep
kill <pid>

# 4. Start a new chat in Claude Desktop (Cmd-N). The first tool call
#    in that new chat causes Claude Desktop to respawn the MCP with the
#    new code — and the new chat's LLM is given the fresh tool list.

Why "new chat" matters even more than "kill the server"

There are two layers that cache things:

1. The MCP server process caches the registered tool list in memory (modules are imported at startup). Killing the process forces a respawn that re-imports the latest code.
2. The chat session caches the tool list it got from the server at chat start, baked into the LLM's context. Newly-added tools don't appear in an existing chat even after the server respawns.

So if you've added a tool (list_services for example) and you want the LLM to be able to call it, you need both:

• The kill+respawn (so the server exposes the new tool at all), AND
• A new chat (so the LLM is told the new tool exists).

Editing an existing tool's behaviour or fixing a bug is different — the tool's name is the same, the LLM already knows about it, so just kill+respawn is enough; the next call hits the new code. Adding or renaming tools requires a new chat.

The same applies to Claude Code: the deferred tools list shown at session start is locked in for that chat. New tools require a new Claude Code session (/clear or starting fresh).

Stale processes

Stray uvx toconline-mcp processes from old terminals can linger and serve stale code. ps aux | grep toconline-mcp shows them; kill <pid> clears them. They're harmless when idle but confusing if you claude mcp add more than one server pointing at the same binary.

Security

• Tokens and client secrets stored in ~/.config/toconline-mcp/credentials.json (0600). The server refuses to start if permissions are looser.
• All logging is to stderr (stdout is reserved for MCP stdio framing). Authorization headers and token fields are redacted from log messages.
• api_request path is constrained to ^/api/... with no ..; write methods require an explicit confirm=true.

License

MIT.