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.

There are deliberately no tools to change, import, or delete anything. The assistant can only read your library, never modify it.

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. There are no tools that change, import, or delete receipts.
• 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 or file it reads - each with the parameters used. So you can always see what was queried (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.
• Read only - no changes, no import, no deletion.
• 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 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="..."

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.