mcp-tiime

A Go MCP server to drive Tiime from
Claude or any MCP agent: invoicing, banking, receipts, expense reports, VAT and exchanges with
the accounting firm. 92 tools, MFA login included.

⚠️ Tiime does not publish an API. This server uses the internal API of the
apps.tiime.fr web application (chronos-api.tiime-apps.com/v1). Routes and formats were
extracted from the web application code and checked against a real account, but nothing is
guaranteed: Tiime may change them without notice. This project is not affiliated with Tiime.

Contents

• Installation
• Quick start
• Example requests
• Tools
• Write safety
• Authentication and MFA
• Configuration
• Behaviors to know
• Development
• Contributing
• License

Installation

Claude Desktop and Cowork (one-click)

Download mcp-tiime.mcpb
from the latest release and double-click it: Claude Desktop installs the extension and asks for
your Tiime email and password. It works on macOS and Windows, in chats and in Cowork. See the
Claude Desktop extension guide.

Prebuilt binaries

Each release ships binaries for Linux, macOS and
Windows (amd64 and arm64), with a checksums.txt file.

tar -xzf mcp-tiime_<version>_darwin_arm64.tar.gz
./mcp-tiime login

Docker

A multi-arch image (linux/amd64, linux/arm64) is published on GitHub Container Registry.
The session cache and downloads live in /data, so keep it in a volume:

# First login, interactive
docker run --rm -it -v mcp-tiime:/data ghcr.io/eko/mcp-tiime login

# MCP server over stdio
claude mcp add tiime -- docker run --rm -i -v mcp-tiime:/data ghcr.io/eko/mcp-tiime

upload_document reads files from the container: mount the folder that holds your receipts
(for instance -v "$HOME/Documents:$HOME/Documents:ro") and pass absolute paths. Mount a host
folder on /data/downloads to get the downloaded PDFs on your machine.

From source

Requirements: Go 1.27 or later.

go build -o bin/mcp-tiime ./cmd/mcp-tiime

# First login (hidden password prompt, MFA code requested when needed)
./bin/mcp-tiime login

# Check: lists the companies the account can access
./bin/mcp-tiime check

Quick start

Claude Code

claude mcp add tiime \
  -e [email protected] \
  -e TIIME_PASSWORD=... \
  -- "$PWD/bin/mcp-tiime"

After rebuilding, restart the server with /mcp → tiime → Reconnect.

Claude Desktop

{
  "mcpServers": {
    "tiime": {
      "command": "/path/to/mcp-tiime/bin/mcp-tiime",
      "env": {
        "TIIME_EMAIL": "[email protected]",
        "TIIME_PASSWORD": "..."
      }
    }
  }
}

TIIME_EMAIL and TIIME_PASSWORD are optional once a session was opened with
mcp-tiime login. They let an agent log in again on its own when the session expires.

Other clients

Cursor, VS Code, Windsurf, Zed, Codex CLI, Gemini CLI and any other stdio MCP client: see the
MCP clients guide.

Example requests

• "What are my last 10 bank transactions without a receipt?"
• "Match the October Qonto invoice with its bank debit."
• "Summarize my inflows and outflows over the last 30 days, by week."
• "How much VAT will I pay next month, and where does it come from?"
• "List the received e-invoices that are still unpaid."
• "Upload this receipt to the expenses to be reimbursed and add it to my November expense report."
• "Create a rule: every wording containing QONTO goes to the QONTO category."
• "Draft an invoice for EKINO: 20 days at €700 excluding VAT."

Tools

Lists are paginated (offset, limit ≤ 100) and return has_more. When the account has a
single company, company_id can be omitted.

The Tested column shows what was checked against a real account: ✅ validated,
🟡 read-only validated, ⬜ never run for real (irreversible writes, or no real case available).

Login

Invoicing

Banking and cash

Categories, rules and tags

Documents

Expense reports and mileage allowances

VAT and revenue book

Accounting firm

Write safety

• Every tool carries MCP annotations: 38 are read-only (readOnlyHint) and 12 are marked
  destructive (destructiveHint), such as finalize_invoice, cancel_invoice and deletions.
  The MCP client can therefore ask for confirmation before running them.
• Writes that replace a whole set in Tiime (documents or invoices matched with a transaction)
  first read the current set and merge it: matching never removes another match.
• Inconsistent input is rejected before any call to Tiime (unknown quote status, negative
  amount, empty expense report, relative file path…).
• Deliberately missing: transfers from the Tiime business account, and sending or
  cancelling VAT returns. These actions are irreversible and deserve a dedicated safeguard
  before being handed to an agent.

Authentication and MFA

The server keeps a refresh token in TIIME_TOKEN_CACHE (0600 file) and renews its access
tokens, valid for 24 hours, on its own. A full login is only needed the first time or when
Tiime expires the session.

Two ways to log in when the account has two-factor authentication:

• Through an agent: the tools fail with a message asking to call start_login. Tiime
  emails a code. The agent reads it with a mail tool (for instance a Gmail MCP, looking for the
  message received after sent_at), then calls complete_login. The password stays in the
  server environment and never goes through the agent.
• In a terminal: ./bin/mcp-tiime login [email|sms|otp] asks for the email and password
  (hidden input) when they are not in the environment, then for the code.

The login goes through the Auth0 Universal Login, like the web application, with PKCE.
Treat the cache as a secret: it grants access to the account.

Configuration

All variables are optional.

Behaviors to know

Observed on a real account:

• VAT on payment: for services, the VAT of an invoice only shows up in
  get_vat_estimate once the payment is received.
• Empty expense reports: Tiime refuses to create an expense report without at least one
  expense.
• E-invoices: Tiime offers no server-side filter; list_einvoices scans the latest 500
  documents.
• Tags: there is no explicit creation. A tag is created when it is applied by name.
• Custom categories: creating them depends on an option enabled by the accounting firm.
  Standard categories can always be adopted.

The technical details of the API (routes, headers, formats and pitfalls) are in
docs/api-tiime.md.

Development

go test -race ./...
golangci-lint run ./...     # v2.15 or later for Go 1.27

To add a tool: add the method to the client in internal/tiime, declare it in the domain
interface in internal/tools, register the tool in the domain register… function, then
update the expected list of TestRegisterListsTools. Project conventions and the full checklist are
described in CONTRIBUTING.md.

Contributing

Contributions are welcome: see CONTRIBUTING.md. Report security issues
privately, as described in SECURITY.md.

License

MIT. This project is not affiliated with Tiime.