fintaro-mcp

A Model Context Protocol server that lets an MCP-capable agent (Claude Desktop, etc.) read your Fintaro invoices and transactions and upload receipts — over the Fintaro API gateway, authenticated with a scoped, bring-your-own ftk_ API key.

The server is read-mostly and PII-safe by construction: get_invoice returns a narrow projection that never includes raw OCR text, raw extraction JSON, or tax-IDs/emails, so attacker-controlled invoice content cannot be injected into the agent's context.

Tools

Prompt: monatsabschluss_check — a guided pre-close review that uses list_unmatched to find transactions still without a receipt.

Agent skills

Ready-to-use, copy-paste skill definitions that teach an MCP-capable agent real Fintaro workflows over these tools live in skills/ — onboarding/setup, the pre-close (Monatsabschluss) review, receipt upload, and an invoice/transaction review. Each is a SKILL.md usable as an agent skill or as a standalone prompt template.

Mint an API key

1. In Fintaro, open Settings → API keys and create a key.
2. Grant the minimum scopes for what you need:
   • read-only review: invoices:read, transactions:read
   • plus receipt upload: add invoices:write
3. Copy the ftk_… key once (it is shown only at creation) and store it in your MCP client's environment. The organization is derived from the key — there is no org parameter to pass.

Configuration

The server rejects any tool call without FINTARO_API_KEY or with a non-https base URL (the configuration is validated on the first tool invocation).

Client config (uvx)

{
  "mcpServers": {
    "fintaro": {
      "command": "uvx",
      "args": ["fintaro-mcp"],
      "env": {
        "FINTARO_API_KEY": "ftk_your_scoped_key"
      }
    }
  }
}

Onboarding a tester

See ONBOARDING.md for a ready-to-send tester summary and a copy-paste onboarding prompt for an MCP-capable agent. The package is not on PyPI yet, so uvx fintaro-mcp does not resolve on its own. Until it is published, install straight from this repo:

{
  "mcpServers": {
    "fintaro": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fintaro-ai/fintaro-mcp", "fintaro-mcp"],
      "env": { "FINTARO_API_KEY": "ftk_your_scoped_key" }
    }
  }
}

Alternatively distribute a built wheel (pip wheel . -w dist --no-deps) and configure the client with uvx --from <path>/fintaro_mcp-*.whl fintaro-mcp.

Development

python3 -m pip install -e ".[dev]"
python3 -m pytest -v