Ask Claude, ChatGPT or Gemini about your own spending

How to connect

Four steps, about a minute

Claude Code, Cursor and other MCP clients

Pocket Clear also runs a read-only remote MCP server with the same data as tools. For Claude Code:

claude mcp add --transport http pocket-clear https://api.pocketclear.app/api/ai/mcp --header "Authorization: Bearer <TOKEN>"

Tools: get_profile, get_summary, list_transactions, list_categories, get_budgets, list_goals, list_accounts. Clients that can't set a header can use https://api.pocketclear.app/api/ai/mcp/t/<TOKEN>.

Try asking

Example prompts

Endpoint reference

Read-only API, v1

Base URL and authentication

Base URL: https://api.pocketclear.app/api/ai/v1. Tokens start with pcai_. Two equivalent ways to send one:

1. Token in the path — works with any tool that can fetch a URL:
   GET https://api.pocketclear.app/api/ai/v1/t/<TOKEN>/summary?month=2026-10
2. Authorization header:
   GET https://api.pocketclear.app/api/ai/v1/summary?month=2026-10 with Authorization: Bearer <TOKEN>

All responses are JSON with Cache-Control: no-store. Start with /me, then /summary for the current month, then answer the question. Assistants should never show the token back to the user or put it in links.

Conventions

• Amounts are plain positive numbers in the user's home currency (currency in /me, ISO 4217). type / kind gives the direction.
• Dates: from and to are inclusive local dates YYYY-MM-DD in the user's time zone. month=YYYY-MM is a shortcut for a whole month. No dates means the current calendar month; only from runs to today. tz=<IANA zone> overrides the time zone.
• Totals follow the app: moneyOut = expenses, moneyIn = income + refunds, net = in − out. Transfers between the user's own accounts, lend/borrow rows and savings-goal set-asides are never income or spending; each transaction carries kind and countsInTotals. Spending by category nets refunds against the category they refund.
• Partner Mode: only the token owner's own data, including entries a partner logged on their behalf.
• Notes appear only when the user turned on Include notes (notesIncluded in /me).
• truncated: true means the account is very large and figures cover the most recently edited 50,000 transactions — partial numbers.

GET /me

Profile and token facts. No email or name. periodSettings are the app's view period and budget start day at the moment the token was created.

{
  "app": "Pocket Clear",
  "apiVersion": "v1",
  "currency": "EUR",
  "secondaryCurrency": null,
  "timeZone": "Europe/Berlin",
  "periodSettings": { "viewPeriod": "monthly", "periodStartDay": 1, "note": "..." },
  "hasPartner": false,
  "dataScope": "own",
  "notesIncluded": false,
  "readOnly": true,
  "tokenExpiresAt": "2027-01-24T10:00:00.000Z",
  "docs": "https://pocketclear.app/developers/api.md"
}

GET /summary?from&to (or ?month)

Totals for a range. share is the percentage of total spending. For a year view, pass from=2026-01-01&to=2026-12-31 and use byMonth.

{
  "currency": "EUR",
  "range": { "from": "2026-10-01", "to": "2026-10-31", "timeZone": "Europe/Berlin" },
  "totals": {
    "moneyIn": 3210.5, "moneyOut": 1874.2, "net": 1336.3,
    "refundsIncludedInMoneyIn": 10.5,
    "savingsSetAside": 200, "savingsWithdrawn": 0,
    "transactionCount": 64
  },
  "spendingByCategory": [ { "categoryId": "…", "category": "Groceries", "amount": 412.3, "share": 22 } ],
  "incomeByCategory":   [ { "categoryId": "…", "category": "Salary", "amount": 3200 } ],
  "byMonth": [ { "month": "2026-10", "moneyIn": 3210.5, "moneyOut": 1874.2, "net": 1336.3 } ],
  "excludedFromTotals": { "transfers": 3, "loanRows": 1 },
  "rules": "…",
  "truncated": false
}

GET /transactions

Individual entries, newest first, in keyset pages.

{
  "currency": "EUR",
  "range": { "from": "2026-10-01", "to": "2026-10-31", "timeZone": "Europe/Berlin" },
  "count": 2,
  "transactions": [
    {
      "id": "…", "date": "2026-10-24", "dateTime": "2026-10-24T18:12:00.000Z",
      "amount": 42.9, "type": "expense", "kind": "expense", "countsInTotals": true,
      "category": "Eating out", "categoryId": "…", "subcategory": "Restaurants",
      "paymentType": "Visa", "payee": "Pizza Place", "tags": ["friends"]
    },
    {
      "id": "…", "date": "2026-10-20", "dateTime": "…",
      "amount": 300, "type": "expense", "kind": "transfer", "countsInTotals": false,
      "category": null, "categoryId": null, "subcategory": null,
      "paymentType": "Checking", "payee": null, "transferTo": "Savings account"
    }
  ],
  "nextCursor": "eyJzIjoi…",
  "truncated": false
}

kind is one of expense, income, refund, transfer, loan, loan_repayment, savings_set_aside, savings_withdrawal; only expense, income and refund count toward totals. Loan rows carry loan: { "kind": "loan" | "repayment", "person": "Sam", "dueDate"? }. note appears only when notes are included.

GET /categories

{ "categories": [
  { "id": "…", "name": "Groceries", "type": "expense", "icon": "🛒", "sharedByPartner": false,
    "subcategories": [ { "id": "…", "name": "Supermarket" } ] }
] }

GET /budgets?from&to (or ?month)

kind is overall, category or subcategory. spentInRange is spending over exactly the range you pass — a month for a monthly budget, a week for a weekly one. Monthly budgets with per-month amounts use the amount for the month of from. Rollover is not included.

{
  "currency": "EUR",
  "range": { "from": "2026-10-01", "to": "2026-10-31", "timeZone": "Europe/Berlin" },
  "budgets": [
    { "id": "…", "kind": "category", "category": "Groceries", "subcategory": null,
      "period": "monthly", "limit": 400, "spentInRange": 412.3, "remaining": -12.3, "percentUsed": 103.08 }
  ],
  "note": "…",
  "truncated": false
}

GET /goals

{ "currency": "EUR", "goals": [
  { "id": "…", "name": "Japan trip", "targetAmount": 3000, "currentAmount": 1250,
    "remaining": 1750, "percentComplete": 41.67, "deadline": "2027-04-01" }
] }

GET /accounts

Payment types with all-time balances: opening balance + money in − money out. Transfers count on both accounts; savings set-asides are not counted (the app's default). A row named "No payment method" collects entries without one.

{ "currency": "EUR", "accounts": [
  { "id": "…", "name": "Checking", "sharedByPartner": false, "openingBalance": 1000,
    "moneyInAllTime": 15400, "moneyOutAllTime": 13120.5, "balance": 3279.5 }
], "note": "…", "truncated": false }

Errors

Errors use HTTP status codes and a JSON body { "error": "<code>", "message": "…", "docs": "…" }.

Rate limits

60 requests a minute and 2,000 a day per token. Answers past the limit are 429 with a Retry-After header.

Open the machine-readable reference (api.md)