AI Connection (MCP)

Receipts Space can act as a local AI server. This lets assistants like Claude, Cursor, or VS Code search and answer questions about your receipts - right on your Mac, without sending your data to the cloud.

Why is this useful?

AI assistants are great at answering questions in plain language - but only when they can reach the right data. That is exactly what this feature does: it connects your AI assistant to your receipt library. Instead of searching, filtering, and adding up yourself, you just ask:

• “How much did I spend at my hosting provider last quarter?”
• “Summarize the latest invoice from the car repair shop.”
• “Which receipts in the Office Supplies category are still unpaid?”
• “Find all restaurant receipts over 50 euros from June.”

The assistant then searches your receipts, reads the recognized text (OCR) where needed, and answers - including doing the math, summarizing, and comparing.

The key point: this happens locally on your Mac. No receipt is uploaded to a third-party cloud just so the AI can “see” it. The assistant only accesses the data it needs for the specific question.

What the assistant can do

The connection provides four read-only tools:

• Search receipts - using the familiar Receipts search syntax, by text, contact, category, tag, date, or amount, additionally filtered by paid/unpaid, expense/income, or marked. Every search also returns a ready-made total (expenses and income) over all matches - so the assistant does not have to add up amounts itself and the total stays correct even for large result sets.
• Read a receipt - all details of a receipt including its recognized text (OCR).
• Fetch a file - the attached PDF or image of a receipt.
• Look up names - the existing category, contact, and tag names, so the assistant knows the real labels instead of guessing.

Out of the box, the assistant can only read your library, never modify it. Changes are only possible through the optional write access.

Write access (optional)

With the “Allow write access” setting, the assistant can also make changes on request - for example “file this cash receipt” or “set the category Office Supplies on all matches”:

• Create entries - from plain values (say, a cash purchase without a receipt) or by importing a file (PDF, image, email, and more), which runs through the normal import pipeline including text recognition, data extraction, and duplicate detection.
• Edit entries - title, amounts, date, category, contact, tags, and more.
• Create, rename, and archive contacts, categories, and tags.

Fixed safety limits always apply:

• Permanent deletion is not possible. Entries can at most be moved to the Trash, and contacts, categories, and tags can only be archived - everything can be undone in the app.
• Entries protected by the revision safety mode can never be modified.
• Every change shows up in the app’s log.

In addition, “Current selection only” limits access to the entries currently selected in the window - or, with no selection, to the visible list. This lets you work with an assistant on just a few receipts without exposing the whole library. In this mode, creating new entries and changing contacts, categories, and tags is disabled.

Privacy and security

What protects you:

• Local only. The server is reachable only on your own computer (127.0.0.1/localhost). It cannot be reached from the internet or the local network.
• Token required. Every request needs a secret access token. Without a valid token it is rejected. You can regenerate the token any time in Settings (existing connections then need to be set up again).
• Read-only by default. Tools that create or change receipts only exist with write access explicitly enabled - and even then, permanent deletion is not possible.
• Only when you want it. The feature is off by default and starts only when you explicitly enable it.
• Transparent. Every access shows up in the app’s visible log: when an AI tool connects, and every single search, file read, or change - each with the parameters used. So you can always see what was queried or changed (see Viewing the log).

Depending on the provider, the AI assistant itself may send parts of your question and the retrieved receipt data to its own cloud service in order to answer. What Receipts Space provides stays local; what your AI assistant then does with it depends on that assistant. So choose an assistant whose privacy you trust, and when in doubt, avoid querying especially sensitive receipts.

Enabling it

1. Open Receipts Space and a library.
2. Go to Settings > MCP Server.
3. Turn on “Enable MCP server (experimental)”.
4. The status switches to “Running on port 28282” (default port, can be changed).

Once the server is running, the settings page shows the URL, the token, and a ready-made setup snippet for the assistant you pick - each with a copy button.

Setting up (examples)

In Settings, choose your assistant under Setup and copy the prepared snippet. The examples below show what that looks like. <token> stands for your personal token from Settings.

Claude Code

In the terminal:

claude mcp add --transport http receipts \
  http://127.0.0.1:28282/mcp \
  --header "Authorization: Bearer <token>"

Then /mcp in Claude Code checks the connection.

Cursor

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

{
  "mcpServers": {
    "receipts": {
      "url": "http://127.0.0.1:28282/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

VS Code (GitHub Copilot)

In the user mcp.json (Command Palette: “MCP: Open User Configuration”) or project-local in .vscode/mcp.json:

{
  "servers": {
    "receipts": {
      "type": "http",
      "url": "http://127.0.0.1:28282/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Claude Desktop

Claude Desktop only speaks the stdio transport locally. The connection goes through the standard mcp-remote bridge (requires Node.js/npx to be installed). In ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "receipts": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://127.0.0.1:28282/mcp",
        "--header", "Authorization: Bearer <token>"
      ]
    }
  }
}

Then restart Claude Desktop.

Other clients

Any assistant that speaks Streamable HTTP with a Bearer token can connect. All you need is:

• URL: http://127.0.0.1:28282/mcp
• Header: Authorization: Bearer <token>

What a conversation might look like

You: How much did I spend on software subscriptions this year?

Assistant: Looks up the matching category (finds “Software”), searches this year’s receipts in that category, adds up the amounts, and gives you the total along with the list of items.

You: Summarize the latest invoice from my tax advisor.

Assistant: Finds the contact, takes the most recent receipt, reads the recognized text, and gives you a short summary with date, amount, and services.

Limitations

• It always uses the currently open library. With multiple libraries open, that is the active one.
• Without write access enabled, no changes are possible; with write access, there is no permanent deletion and no changing of entries protected by the revision safety mode.
• The server uses a fixed port. If it is taken, the status shows an error - then pick a different port in Settings.

Viewing the log

Every access through the AI connection is recorded in the app’s logbook and tagged with #mcp - so it stays transparent which tool read or changed what and when. You will see:

• when an AI tool connects, e.g. #mcp Claude Code 1.2.3 connected
• every search and every receipt read, including parameters, e.g. #mcp search_receipts query="Hotel", limit=10 or #mcp get_receipt uid="..."
• every change made through write access, including the values passed, e.g. #mcp update_receipt uid="...", title="..."

Troubleshooting

• Status “Failed”: The port is probably in use. Choose a different port.
• The assistant gets a 401 error: The token is wrong. Copy or regenerate the token and update the setup.
• “No receipts library is currently open”: Open a library in the app.

If you have any further questions, our support team is happy to help.