# NeverLose for AI assistants

NeverLose is a personal finance app for iOS and Android. Its MCP server lets an AI assistant (Claude, ChatGPT, Codex, Cursor and others) read the accounts, balances and transactions of a user, and add, change, merge and delete transactions, accounts, account groups, categories, payees, projects and tags. It can also change the base currency.

- MCP server URL: https://never.malkindev.com/mcp
- Transport: Streamable HTTP. Authorization: OAuth 2.1. The user signs in with Google or Apple.
- This page as HTML: https://never.malkindev.com/docs

## For agents: help a person connect

1. First, the person signs in to the NeverLose app (iOS or Android) with Google or Apple. On the web sign-in page, the person must use the same account. Else the page shows "No NeverLose account".
2. Ask which assistant the person uses. Give the steps for it from the section "Connect" below.
3. The sign-in page has the switch "Add, change and delete data: accounts, categories, transactions, settings". It is on by default. Without it, the assistant can only read.
4. After the sign-in, call `get_overview` to check the connection.
5. If you are an agent that can add MCP servers yourself (for example Claude Code or Codex), add the server with the command for your client. The person signs in on a web page.

To disconnect an assistant: in the NeverLose app, open Account → Assistants.

## Connect

### Claude

1. Open Customize → Connectors.
1. Click + Add, then Add custom connector.
1. Name: NeverLose. URL: https://never.malkindev.com/mcp. Click Add.
1. Click Connect. Sign in with the Google or Apple account of your NeverLose app, then click Allow.
1. In a chat, click + → Connectors and turn on NeverLose.

On Team and Enterprise plans, an owner adds the connector first in Organization settings → Connectors. The names of the menus can be different in your version.

### ChatGPT

1. Turn on Developer mode: Settings → Apps → Advanced settings.
1. Add a custom MCP server. Name: NeverLose. URL: https://never.malkindev.com/mcp. Authentication: OAuth.
1. Sign in with the Google or Apple account of your NeverLose app, then click Allow.
1. In a chat, select NeverLose in the tools menu, or type @NeverLose.

Developer mode is not available on all plans. The names of the menus can be different in your version.

### Claude Code

```
claude mcp add --transport http --scope user neverlose https://never.malkindev.com/mcp
```

1. Run the command.
1. In Claude Code, type /mcp, select neverlose and sign in.

### Codex

```
codex mcp add neverlose --url https://never.malkindev.com/mcp
codex mcp login neverlose
```

1. Run the commands. The second command opens the sign-in page.

### Cursor

```
{
  "mcpServers": {
    "neverlose": { "url": "https://never.malkindev.com/mcp" }
  }
}
```

1. Add this to ~/.cursor/mcp.json.
1. In Cursor, open the list of MCP servers, find neverlose and click Connect.

### VS Code

```
code --add-mcp '{"name":"neverlose","type":"http","url":"https://never.malkindev.com/mcp"}'
```

1. Run the command.
1. Run the command MCP: List Servers, select neverlose, then Start Server. Allow the sign-in.

### Gemini CLI

```
gemini mcp add --transport http -s user neverlose https://never.malkindev.com/mcp
```

1. Run the command.
1. In Gemini CLI, type /mcp auth neverlose and sign in.

### Other

1. Use a client that supports remote MCP servers (Streamable HTTP) with OAuth.
1. Give it the URL https://never.malkindev.com/mcp.
1. You do not need a client ID or a secret: the client registers itself.

## What a person can ask

- "How much did I spend on food last month?"
- "Show the balance of all my accounts."
- "Add a coffee for 4.50 from my card today."
- "Add the category Donuts under Food, then add 10 for a donut."
- "Put all Uber rows without a category into Transport."
- "Compare my expenses by category: this year and last year."
- "Which payees got the most money from me this month?"
- "Tag all hotel expenses of last week with Trip."
- "Merge the categories Cafe and Coffee."
- "Set the balance of my card to 1234.56."
- "Delete the account Old card with its transactions."
- "Make EUR my main currency."
- "Undo the last change."

## Safety

- The person signs in with the account of the NeverLose app and chooses: only read, or also add, change and delete data.
- When `update_transactions`, `delete_transactions`, `update_catalog_items` or `delete_catalog_items` changes more than one row, the first call changes nothing and gives a preview. The assistant applies it only with the confirm token of the preview, after the person agrees.
- `add_transactions` and `add_catalog_items` add the rows at once.
- `undo_change` undoes a change. With the `change_id` of a change, it undoes a change of any assistant of the same person. Only the assistant that made the change gets the `change_id`, so the person gives it to the other assistant. Without a `change_id`, it undoes only the last change of this assistant. Rows that changed later (on a device or by another change) stay as they are.
- The person can disconnect an assistant at any time in the app: Account → Assistants.
- NeverLose keeps the records that the person enters or asks the assistant to enter. It does not connect to banks, does not hold or move money and does not give financial, tax or investment advice. The exchange rates are for information only.
- Support: contact@malkindev.com.

## Rules for the assistant

NeverLose is a personal finance app. These tools read and change the data of the user.

- Call get_overview first: it gives the base currency, today, the accounts, their groups and the balances.
- Amounts are decimal numbers as text, with a point and no thousands separators ("1250.50"), with a currency code next to them. Totals are in the base currency. Totals do not include transfers and planned transactions that wait for a confirmation (unreconciled), as in the app.
- Dates are local dates (YYYY-MM-DD) in the time zone of the user. A date range includes both dates.
- Filters accept names or IDs of accounts, categories, payees, projects and tags. Names of the app in all its languages work too. Use list_catalog to see the names. The outputs give the names of the built-in categories and account groups in the app language of the user, as the app shows them.
- Do the work for the user with the tools. If an account, a category, a project or a tag is missing, add it with add_catalog_items (it does not add an item with a name that exists), then use it. If the user has no accounts, the account name in add_transactions adds the first account (cash, base currency).
- update_catalog_items changes accounts, groups, categories, projects, payees and tags; delete_catalog_items deletes them as the app does or merges one into another. update_settings changes the base currency and the other currencies of the balance.
- A transfer moves money from one account to another; it is one item. Transfers are not income or expense in the totals.
- list_transactions gives rows as a table (columns and rows). Use next_cursor for the next page.
- add_transactions and add_catalog_items add the rows at once. A known payee gives its category, project and tags to a new transaction that has none. update_transactions and delete_transactions choose the transactions by ids or by a filter with at least one condition. When a change touches more than one row, the first call changes nothing and gives a preview: show it to the user and apply it only after the user agrees (call again with the same arguments and the confirm token).
- Each change has a change_id. undo_change undoes it, also a change of another assistant of the same user (the user gives you its change_id); without change_id it undoes your last change. Rows that changed later (on a device or by another change) stay. An added item that a transaction or another item now uses stays.
- In add_transactions, give each new transaction a new request_id. Use the same request_id only to try a call again: then the row is not added two times.
- The exchange rates come from public sources. The server gets them about every hour (crypto currencies about every 10 minutes), but the sources of the other currencies publish new rates only one time a day, on business days. These rates are good for budget totals. When the user needs an exact current rate, or a currency is in missing_rates, get a current rate yourself, convert the amounts in their own currencies (the outputs give them), and tell the user which rate and which date you used.

## Formats

- Amount: A decimal number as text, with a point: "1250.50". No sign and no thousands separators. Not more fraction digits than the currency uses: none for JPY, KRW and the other currencies without minor units. Not more than 1000000000000 of a fiat currency or 10000000000 of a crypto currency. Only the balance of a new account can have a sign: "-250.00".
- Date: YYYY-MM-DD: a local date in the time zone of the user. A range includes both dates.
- Month: YYYY-MM, in the month groups of get_totals.
- Time: RFC 3339 in UTC, for example rates_updated_at.
- Name: Account groups, accounts, categories, payees, projects and tags by name or ID. A subcategory can have a path: Food / Cafe. A new name has no spaces at the ends and one space between the words.
- Color: #RRGGBB, for example #4CAF50.

## Tools

### `get_overview`: Overview

Access: read. Gives the base currency, the date today, the time zone, all accounts with their balances and groups, and the total balance in the base currency.

Input:

No input.

Output:

- `base_currency` (string)
- `rates` (object): The rates that the output used: the value of 1 unit of each currency in the base currency, as a decimal number. Only the currencies of the output; the base currency is not in it.
- `rates_updated_at` (string or null): The time of the oldest rate in rates, or null when the output converts nothing.
- `missing_rates` (list of string): The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
- `second_currency` (string or null): The second currency of the balance in the app, or null.
- `third_currency` (string or null): The third currency of the balance in the app, or null.
- `has_accounts` (boolean): False if the user has no accounts. Then add_transactions adds the first account.
- `account_groups` (list of object): The groups of the accounts, in the order of the app.
  - `id` (string)
  - `name` (string)
  - `accounts` (list of string): The IDs of the accounts in the group.
- `today` (string)
- `time_zone` (string)
- `accounts` (list of object)
  - `id` (string)
  - `name` (string)
  - `type` (string)
  - `currency` (string)
  - `balance` (string)
  - `balance_base` (string or null): The balance in the base currency, or null if there is no exchange rate.
  - `in_total` (boolean): True if the total balance includes the account.
- `total` (object)
  - `amount` (string): The total balance of the accounts with in_total, in the base currency, without the currencies in missing_rates.
  - `currency` (string)
- `transactions` (integer): The number of transactions. A transfer is one transaction.
- `first_date` (string or null): The local date of the first transaction, or null if there are no transactions.
- `last_date` (string or null): The local date of the last transaction, or null if there are no transactions.

### `list_transactions`: List transactions

Access: read. Gives the transactions that match a filter as a table, the newest first. A page has not more than 500 rows. To get the next page, use next_cursor.

Input:

- `from` (string): The first local date, YYYY-MM-DD. The range includes it.
- `to` (string): The last local date, YYYY-MM-DD. The range includes it.
- `accounts` (list of string): The names or the IDs of accounts. A transfer matches if one of its two accounts matches.
- `categories` (list of string): The names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.
- `payees` (list of string): The names or the IDs of payees.
- `projects` (list of string): The names or the IDs of projects. Their subprojects also match.
- `tags` (list of string): The names or the IDs of tags. A row matches if it has one of the tags.
- `kinds` (list of string): The kinds of transactions. Values: `income`, `expense`, `transfer`.
- `min_amount` (string): The minimum amount, as a decimal number, in the currency of each row.
- `max_amount` (string): The maximum amount, as a decimal number, in the currency of each row.
- `currency` (string): The currency code of the rows, for example USD.
- `text` (string): A text in the note or in the name of the payee.
- `no_category` (boolean): True: only income and expense rows that have no category.
- `status` (string): The reconcile status. Values: `unreconciled`, `cleared`, `reconciled`.
- `planned` (boolean): True: only the rows that a plan made. False: only the other rows.
- `limit` (integer): The number of rows on a page: 1 to 500. If you do not give it, 100.
- `cursor` (string): The next_cursor of the previous page.

Output:

- `columns` (list of string): The names of the values in each row.
- `rows` (list of list of any): Each row has the values in the order of columns: id; date (local, YYYY-MM-DD); kind; amount (more than 0, the kind gives the direction); currency; account; to_account, to_amount and to_currency (only for a transfer, else null); category (a path such as Food / Cafe, null for a transfer); payee; project; tags (a list, or null); note; status; planned (true for a row that a plan made).
- `matches` (integer): The number of transactions that match the filter, on all pages.
- `next_cursor` (string or null): To get the next page, give this value as cursor. It is null on the last page.

### `get_totals`: Totals

Access: read. Gives the income and the expense of the transactions that match a filter, in the base currency, as the reports of the app: without transfers and without planned transactions that wait for a confirmation (unreconciled). You can put the totals in one or two levels of groups.

Input:

- `from` (string): The first local date, YYYY-MM-DD. The range includes it.
- `to` (string): The last local date, YYYY-MM-DD. The range includes it.
- `accounts` (list of string): The names or the IDs of accounts. A transfer matches if one of its two accounts matches.
- `categories` (list of string): The names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.
- `payees` (list of string): The names or the IDs of payees.
- `projects` (list of string): The names or the IDs of projects. Their subprojects also match.
- `tags` (list of string): The names or the IDs of tags. A row matches if it has one of the tags.
- `kinds` (list of string): The kinds of transactions. Values: `income`, `expense`, `transfer`.
- `min_amount` (string): The minimum amount, as a decimal number, in the currency of each row.
- `max_amount` (string): The maximum amount, as a decimal number, in the currency of each row.
- `currency` (string): The currency code of the rows, for example USD.
- `text` (string): A text in the note or in the name of the payee.
- `no_category` (boolean): True: only income and expense rows that have no category.
- `status` (string): The reconcile status. Values: `unreconciled`, `cleared`, `reconciled`.
- `planned` (boolean): True: only the rows that a plan made. False: only the other rows.
- `group_by` (list of string): The groups of the totals: zero, one or two values. Values: `category`, `payee`, `project`, `account`, `month`.
- `limit` (integer): The maximum number of groups: 1 to 500. If you do not give it, 100.

Output:

- `base_currency` (string)
- `rates` (object): The rates that the output used: the value of 1 unit of each currency in the base currency, as a decimal number. Only the currencies of the output; the base currency is not in it.
- `rates_updated_at` (string or null): The time of the oldest rate in rates, or null when the output converts nothing.
- `missing_rates` (list of string): The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
- `group_by` (list of string)
- `rows` (list of object): The groups. The list is empty if group_by is empty.
  - `group` (list of string): One value for each item of group_by. Null is for no value.
  - `income` (string)
  - `expense` (string)
  - `net` (string)
  - `count` (integer): The number of transactions in the group.
  - `missing_rates` (list of string): The currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.
- `income` (string)
- `expense` (string)
- `net` (string)
- `count` (integer): The number of transactions.
- `more_groups` (integer): The number of groups that are not shown because of the limit.
- `by_currency` (list of object): The income and the expense of all rows in each currency, before the conversion to the base currency.
  - `currency` (string)
  - `income` (string)
  - `expense` (string)

### `list_catalog`: List names

Access: read. Gives the account groups, accounts, categories, payees, projects or tags, with their IDs, their fields and the number of transactions of each. The item that is used most is first.

Input:

- `kind` (string, required): The type of items to list. Values: `account_groups`, `accounts`, `categories`, `payees`, `projects`, `tags`.
- `query` (string): Only the names that contain this text. Upper case and lower case are the same.
- `limit` (integer): The maximum number of items: 1 to 500. If you do not give it, 200.

Output:

- `kind` (string)
- `items` (list of object): The items. Account groups are in the order of the app. For the other kinds, the item that is used most is first.
  - `id` (string)
  - `name` (string)
  - `type` (string or null, optional): For a category: income or expense. For an account: the type of the account.
  - `path` (string or null, optional): For a subcategory: the path with the parent categories, for example Food / Cafe.
  - `parent` (string or null, optional): The name of the parent category or the parent project.
  - `currency` (string or null, optional)
  - `color` (string or null, optional): The color as #RRGGBB.
  - `icon` (string or null, optional): For a category: the icon key.
  - `favorite` (boolean, optional): True for a category that the user marked as a favorite.
  - `builtin` (boolean, optional): True for a built-in category or account group of the app. Its name is in the app language of the user, as the app shows it.
  - `group` (string or null, optional): For an account: the name of its group.
  - `in_balance` (boolean or null, optional): For an account: true if the total balance includes it.
  - `initial_balance` (string or null, optional): For an account: the balance before all transactions.
  - `balance` (string or null, optional): For an account: the balance now.
  - `accounts` (list of string, optional): For an account group: the IDs of its accounts.
  - `status` (string or null, optional): For a project: active or inactive.
  - `limit` (string or null, optional): For a project: the budget, in the currency of the project.
  - `date` (string or null, optional): For a project: the local date.
  - `description` (string or null, optional): For a project: the note.
  - `category` (string or null, optional): For a payee: the category (a path) that a new transaction with the payee gets.
  - `project` (string or null, optional): For a payee: the project that a new transaction with the payee gets.
  - `tags` (list of string, optional): For a payee: the tags that a new transaction with the payee gets.
  - `count` (integer): The number of transaction rows that use the item. For an account group: the number of its accounts.
- `more` (integer): The number of items that are not shown because of the limit.

### `add_transactions`: Add transactions

Access: write. Adds 1 to 100 expenses, incomes or transfers at once. Give accounts, categories, payees, projects and tags by name or ID. A new payee name adds a new payee. If the user has no accounts, the account name adds the first account.

Input:

- `transactions` (list of object, required): The transactions to add: 1 to 100.
  - `request_id` (string): A text that is different for each new transaction, in all calls. If a call has the request_id of an earlier call, the row is not added again. Use the same request_id only when you send a call again.
  - `kind` (string, required): The kind of the transaction. Values: `income`, `expense`, `transfer`.
  - `date` (string): The local date, YYYY-MM-DD, with a year from 1900 to 2100. If you do not give it, the date is today.
  - `account` (string, required): The name or the ID of the account. For a transfer, the account that the money goes out of. If the user has no accounts, a new name adds a cash account in the base currency.
  - `amount` (string, required): The amount in the currency of the account, more than 0, as a decimal number with a point. A currency without minor units (for example JPY) takes a whole number.
  - `to_account` (string): For a transfer: the account that the money goes into.
  - `to_amount` (string): For a transfer between two currencies: the amount that goes into to_account, in its currency.
  - `category` (string): The name, the path or the ID of the category. The type of the category must be the same as the kind.
  - `payee` (string): The name or the ID of the payee. A new name adds a new payee. A known payee gives its category, project and tags when you do not give them.
  - `project` (string): The name or the ID of the project.
  - `tags` (list of string): The names or the IDs of the tags.
  - `note` (string): A note.
  - `status` (string): The reconcile status. If you do not give it: unreconciled for an income or an expense with a date after today, else reconciled. Values: `unreconciled`, `cleared`, `reconciled`.

Output:

- `change_id` (string or null): To undo this call, give this value to undo_change.
- `added` (integer)
- `ids` (list of string): The ID of each transaction, in the order of the input.
- `new_payees` (list of string): The names of the payees that the call added.
- `new_accounts` (list of string): The names of the accounts that the call added. Only a user with no accounts gets a new account.
- `already_added` (integer): The number of rows that an earlier call with the same request_id added. These rows are not added again.

### `add_catalog_items`: Add accounts and categories

Access: write. Adds 1 to 100 account groups, accounts, categories, projects, payees and tags at once. An item can refer to an item of the same call. If an item of the same kind already has the name (a category: also the same type and parent), the call does not add it again and gives it in existing.

Input:

- `account_groups` (list of object): New groups of accounts.
  - `name` (string, required): The name of the group.
- `accounts` (list of object): New accounts.
  - `name` (string, required): The name of the account.
  - `currency` (string): The currency code, for example EUR. If you do not give it, the base currency.
  - `type` (string): The type of the account. If you do not give it, bank. Values: `cash`, `bank`, `asset`, `creditCard`, `debitCard`, `investment`, `liability`, `loan`, `receivable`, `taxLiability`.
  - `group` (string): The name or the ID of the account group. If you do not give it, Cards and accounts.
  - `balance` (string): The balance now, in the currency of the account, as a decimal number with a point. It can be negative, for example -250.00 for a credit card debt. If you do not give it, 0.
  - `in_balance` (boolean): False: the total balance does not include the account. If you do not give it, true.
  - `color` (string): The color as #RRGGBB.
- `categories` (list of object): New categories and subcategories.
  - `name` (string, required): The name of the category, without the parent.
  - `type` (string): The type of the category. If you do not give it, expense. A subcategory has the type of its parent. Values: `expense`, `income`.
  - `parent` (string): For a subcategory: the name or the ID of a top-level category. A subcategory cannot have subcategories.
  - `icon` (string): The icon key. If you do not give it, the icon of the parent, else unknown. Values: `alien`, `backhoe`, `biohazard`, `book`, `brightness`, `car`, `cash`, `ghost`, `gift`, `groceries`, `health`, `home`, `kitchen`, `laptop`, `scooter`, `shirt`, `sun`, `tinder`, `unknown`, `virus`, `mat:directions_car`, `mat:local_car_wash`, `mat:build`, `mat:local_gas_station`, `mat:local_parking`, `mat:local_taxi`, `mat:directions_bus`, `mat:directions_bike`, `mat:directions_transit`, `mat:business_center`, `mat:work`, `mat:apartment`, `mat:calculate`, `mat:badge`, `mat:devices`, `mat:desktop_mac`, `mat:receipt_long`, `mat:receipt`, `mat:shield`, `mat:gavel`, `mat:payments`, `mat:attach_money`, `mat:account_balance`, `mat:account_balance_wallet`, `mat:child_care`, `mat:family_restroom`, `mat:child_friendly`, `mat:school`, `mat:sports_soccer`, `mat:sports_basketball`, `mat:checkroom`, `mat:toys`, `mat:home`, `mat:grass`, `mat:water_drop`, `mat:electric_bolt`, `mat:bolt`, `mat:local_fire_department`, `mat:cleaning_services`, `mat:wifi`, `mat:phone_android`, `mat:tv`, `mat:volunteer_activism`, `mat:pets`, `mat:local_hospital`, `mat:medical_services`, `mat:local_pharmacy`, `mat:fitness_center`, `mat:spa`, `mat:local_laundry_service`, `mat:content_cut`, `mat:health_and_safety`, `mat:restaurant`, `mat:local_cafe`, `mat:local_bar`, `mat:local_grocery_store`, `mat:shopping_bag`, `mat:shopping_cart`, `mat:card_giftcard`, `mat:flight`, `mat:flight_takeoff`, `mat:hotel`, `mat:museum`, `mat:sim_card`, `mat:movie`, `mat:subscriptions`, `mat:savings`, `mat:bar_chart`, `mat:trending_down`, `mat:storefront`, `mat:campaign`, `mat:menu_book`, `mat:handyman`, `mat:outdoor_grill`, `mat:hiking`, `mat:nature_people`, `mat:sell`, `mat:request_quote`, `mat:money_off`, `mat:favorite`, `mat:star`.
  - `color` (string): The color as #RRGGBB.
- `projects` (list of object): New projects.
  - `name` (string, required): The name of the project.
  - `description` (string): A note about the project.
  - `status` (string): The status of the project. If you do not give it, active. Values: `active`, `inactive`.
  - `currency` (string): The currency code of the limit. If you do not give it, the base currency.
  - `limit` (string): The budget of the project in its currency, as a decimal number with a point.
  - `date` (string): The local date of the project, YYYY-MM-DD. If you do not give it, today.
  - `parent` (string): The name or the ID of the parent project.
- `payees` (list of object): New payees.
  - `name` (string, required): The name of the payee.
  - `category` (string): The category that a new transaction with this payee gets: a name, a path or an ID.
  - `project` (string): The project that a new transaction with this payee gets.
  - `tags` (list of string): The tags that a new transaction with this payee gets.
- `tags` (list of object): New tags.
  - `name` (string, required): The name of the tag.
  - `color` (string): The color as #RRGGBB.

Output:

- `change_id` (string or null): To undo this call, give this value to undo_change. Null if the call added nothing.
- `created` (list of object): The items that the call added.
  - `kind` (string): The list of the item, as the kind of list_catalog.
  - `id` (string)
  - `name` (string): The name. For a subcategory, the path, for example Food / Cafe.
- `existing` (list of object): The items that already had the name. The call did not add or change them.
  - `kind` (string): The list of the item, as the kind of list_catalog.
  - `id` (string)
  - `name` (string): The name. For a subcategory, the path, for example Food / Cafe.

### `update_catalog_items`: Change accounts and categories

Access: change. Changes 1 to 100 account groups, accounts, categories, projects, payees and tags. Give each item by name or ID in ref. An account balance is the balance now. When more than one row changes, the first call changes nothing and gives a preview with a confirm token: show the preview to the user, then call again with the same arguments and the token.

Input:

- `account_groups` (list of object): Changes of account groups.
  - `ref` (string, required): The name or the ID of the group.
  - `name` (string): The new name.
  - `position` (integer): The new place of the group in the list, from 1. The other groups move.
- `accounts` (list of object): Changes of accounts.
  - `ref` (string, required): The name or the ID of the account.
  - `name` (string): The new name.
  - `type` (string): The type of the account. Values: `cash`, `bank`, `asset`, `creditCard`, `debitCard`, `investment`, `liability`, `loan`, `receivable`, `taxLiability`.
  - `group` (string): The name or the ID of the account group.
  - `balance` (string): The balance now, in the currency of the account, as a decimal number with a point. It can be negative. The opening balance changes by the difference, as in the app.
  - `in_balance` (boolean): False: the total balance does not include the account.
  - `color` (string): The color as #RRGGBB.
  - `currency` (string): The currency code. Only an account without transactions and plans can change its currency.
- `categories` (list of object): Changes of categories.
  - `ref` (string, required): The name, the path or the ID of the category.
  - `name` (string): The new name, without the parent.
  - `parent` (string): A top-level category of the same type. An empty text makes it a top-level category. The type of a category does not change.
  - `icon` (string): The icon key. Values: `alien`, `backhoe`, `biohazard`, `book`, `brightness`, `car`, `cash`, `ghost`, `gift`, `groceries`, `health`, `home`, `kitchen`, `laptop`, `scooter`, `shirt`, `sun`, `tinder`, `unknown`, `virus`, `mat:directions_car`, `mat:local_car_wash`, `mat:build`, `mat:local_gas_station`, `mat:local_parking`, `mat:local_taxi`, `mat:directions_bus`, `mat:directions_bike`, `mat:directions_transit`, `mat:business_center`, `mat:work`, `mat:apartment`, `mat:calculate`, `mat:badge`, `mat:devices`, `mat:desktop_mac`, `mat:receipt_long`, `mat:receipt`, `mat:shield`, `mat:gavel`, `mat:payments`, `mat:attach_money`, `mat:account_balance`, `mat:account_balance_wallet`, `mat:child_care`, `mat:family_restroom`, `mat:child_friendly`, `mat:school`, `mat:sports_soccer`, `mat:sports_basketball`, `mat:checkroom`, `mat:toys`, `mat:home`, `mat:grass`, `mat:water_drop`, `mat:electric_bolt`, `mat:bolt`, `mat:local_fire_department`, `mat:cleaning_services`, `mat:wifi`, `mat:phone_android`, `mat:tv`, `mat:volunteer_activism`, `mat:pets`, `mat:local_hospital`, `mat:medical_services`, `mat:local_pharmacy`, `mat:fitness_center`, `mat:spa`, `mat:local_laundry_service`, `mat:content_cut`, `mat:health_and_safety`, `mat:restaurant`, `mat:local_cafe`, `mat:local_bar`, `mat:local_grocery_store`, `mat:shopping_bag`, `mat:shopping_cart`, `mat:card_giftcard`, `mat:flight`, `mat:flight_takeoff`, `mat:hotel`, `mat:museum`, `mat:sim_card`, `mat:movie`, `mat:subscriptions`, `mat:savings`, `mat:bar_chart`, `mat:trending_down`, `mat:storefront`, `mat:campaign`, `mat:menu_book`, `mat:handyman`, `mat:outdoor_grill`, `mat:hiking`, `mat:nature_people`, `mat:sell`, `mat:request_quote`, `mat:money_off`, `mat:favorite`, `mat:star`.
  - `color` (string): The color as #RRGGBB.
  - `favorite` (boolean): True: the app shows the category in the favorites group. False: it does not.
- `projects` (list of object): Changes of projects.
  - `ref` (string, required): The name or the ID of the project.
  - `name` (string): The new name.
  - `description` (string): A note about the project.
  - `status` (string): The status of the project. Values: `active`, `inactive`.
  - `currency` (string): The currency code of the limit. Without a new limit, the limit keeps its number.
  - `limit` (string): The budget in the currency of the project, as a decimal number with a point. An empty text removes the limit.
  - `date` (string): The local date of the project, YYYY-MM-DD.
  - `parent` (string): The name or the ID of the parent project. An empty text makes it a top-level project.
- `payees` (list of object): Changes of payees.
  - `ref` (string, required): The name or the ID of the payee.
  - `name` (string): The new name.
  - `category` (string): The category that a new transaction with this payee gets. An empty text removes it.
  - `project` (string): The project that a new transaction with this payee gets. An empty text removes it.
  - `tags` (list of string): The tags that a new transaction with this payee gets. They replace the tags. An empty list removes them.
- `tags` (list of object): Changes of tags.
  - `ref` (string, required): The name or the ID of the tag.
  - `name` (string): The new name.
  - `color` (string): The color as #RRGGBB.
- `confirm` (string): The confirm token that the preview gave.

Output:

- `preview` (boolean): True if nothing changed yet: this is a preview.
- `change_id` (string or null, optional): After the change: to undo it, give this value to undo_change.
- `items` (list of object): The items of the input and what the call does to them.
  - `kind` (string): The list of the item, as the kind of list_catalog.
  - `id` (string)
  - `name` (string)
  - `action` (string): changed, deleted or merged.
  - `into` (object or null, optional): For a merged item: the item that got its uses.
    - `kind` (string): The list of the item, as the kind of list_catalog.
    - `id` (string)
    - `name` (string): The name. For a subcategory, the path, for example Food / Cafe.
- `rows` (list of object): The number of rows of each kind that the call changes or deletes, the items included.
  - `kind` (string): The kind of the rows, for example transactions or planner_plans.
  - `changed` (integer)
  - `deleted` (integer)
- `confirm` (string or null, optional): To apply the change, call again with the same arguments and this token.
- `effect` (object or null, optional): In a preview: the income and the expense of the changed transactions before and after the change, in the base currency.
  - `base_currency` (string)
  - `rates` (object): The rates that the output used: the value of 1 unit of each currency in the base currency, as a decimal number. Only the currencies of the output; the base currency is not in it.
  - `rates_updated_at` (string or null): The time of the oldest rate in rates, or null when the output converts nothing.
  - `missing_rates` (list of string): The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
  - `before` (object)
    - `income` (string)
    - `expense` (string)
  - `after` (object)
    - `income` (string)
    - `expense` (string)
  - `by` (string): The type of group in groups.
  - `groups` (list of object): The groups that have different totals after the change. The largest change is first. Not more than 20.
    - `group` (string or null): The name of the group, or null for no value.
    - `before` (object)
      - `income` (string)
      - `expense` (string)
    - `after` (object)
      - `income` (string)
      - `expense` (string)
    - `missing_rates` (list of string): The currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.
  - `more_groups` (integer)

### `delete_catalog_items`: Delete or merge accounts and categories

Access: change. Deletes 1 to 100 account groups, accounts, categories, projects, payees and tags, as the app does: transactions, plans and payees lose the item. merge_into moves all uses of a category, project, payee or tag to another item, then deletes it. When more than the item changes, the first call changes nothing and gives a preview with a confirm token: show the preview to the user, then call again with the same arguments and the token.

Input:

- `account_groups` (list of object): Account groups to delete.
  - `ref` (string, required): The name or the ID of the group. Its accounts move to the first group. The last group cannot be deleted.
- `accounts` (list of object): Accounts to delete.
  - `ref` (string, required): The name or the ID of the account. The plans of the account are deleted too.
  - `transactions` (string): keep: the transactions stay, as in the app. delete: the transactions of the account are deleted too. If you do not give it, keep. Values: `keep`, `delete`.
- `categories` (list of object): Categories to delete or merge. Transactions, plans and payees lose a deleted category; its subcategories become top-level categories.
  - `ref` (string, required): The name or the ID of the item.
  - `merge_into` (string): The name or the ID of an item of the same kind that gets all uses of the item: transactions, plans, payee presets and subitems. A category merges only into a category of the same type.
- `projects` (list of object): Projects to delete or merge.
  - `ref` (string, required): The name or the ID of the item.
  - `merge_into` (string): The name or the ID of an item of the same kind that gets all uses of the item: transactions, plans, payee presets and subitems. A category merges only into a category of the same type.
- `payees` (list of object): Payees to delete or merge.
  - `ref` (string, required): The name or the ID of the item.
  - `merge_into` (string): The name or the ID of an item of the same kind that gets all uses of the item: transactions, plans, payee presets and subitems. A category merges only into a category of the same type.
- `tags` (list of object): Tags to delete or merge.
  - `ref` (string, required): The name or the ID of the item.
  - `merge_into` (string): The name or the ID of an item of the same kind that gets all uses of the item: transactions, plans, payee presets and subitems. A category merges only into a category of the same type.
- `confirm` (string): The confirm token that the preview gave.

Output:

- `preview` (boolean): True if nothing changed yet: this is a preview.
- `change_id` (string or null, optional): After the change: to undo it, give this value to undo_change.
- `items` (list of object): The items of the input and what the call does to them.
  - `kind` (string): The list of the item, as the kind of list_catalog.
  - `id` (string)
  - `name` (string)
  - `action` (string): changed, deleted or merged.
  - `into` (object or null, optional): For a merged item: the item that got its uses.
    - `kind` (string): The list of the item, as the kind of list_catalog.
    - `id` (string)
    - `name` (string): The name. For a subcategory, the path, for example Food / Cafe.
- `rows` (list of object): The number of rows of each kind that the call changes or deletes, the items included.
  - `kind` (string): The kind of the rows, for example transactions or planner_plans.
  - `changed` (integer)
  - `deleted` (integer)
- `confirm` (string or null, optional): To apply the change, call again with the same arguments and this token.
- `effect` (object or null, optional): In a preview: the income and the expense of the changed transactions before and after the change, in the base currency.
  - `base_currency` (string)
  - `rates` (object): The rates that the output used: the value of 1 unit of each currency in the base currency, as a decimal number. Only the currencies of the output; the base currency is not in it.
  - `rates_updated_at` (string or null): The time of the oldest rate in rates, or null when the output converts nothing.
  - `missing_rates` (list of string): The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
  - `before` (object)
    - `income` (string)
    - `expense` (string)
  - `after` (object)
    - `income` (string)
    - `expense` (string)
  - `by` (string): The type of group in groups.
  - `groups` (list of object): The groups that have different totals after the change. The largest change is first. Not more than 20.
    - `group` (string or null): The name of the group, or null for no value.
    - `before` (object)
      - `income` (string)
      - `expense` (string)
    - `after` (object)
      - `income` (string)
      - `expense` (string)
    - `missing_rates` (list of string): The currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.
  - `more_groups` (integer)

### `update_transactions`: Change transactions

Access: change. Changes fields of transactions that you select by IDs or by a filter, also the kind, and the accounts and the amounts of a transfer. If one transaction by ID cannot change, the call gives an error; a batch lists such transactions in skipped. When more than one transaction changes, the first call changes nothing and gives a preview with a confirm token: show the preview to the user, then call again with the same arguments and the token.

Input:

- `ids` (list of string): The IDs of the transactions, from list_transactions. Give ids or filter, not the two.
- `filter` (object): A filter with one or more conditions, as in list_transactions.
  - `from` (string): The first local date, YYYY-MM-DD. The range includes it.
  - `to` (string): The last local date, YYYY-MM-DD. The range includes it.
  - `accounts` (list of string): The names or the IDs of accounts. A transfer matches if one of its two accounts matches.
  - `categories` (list of string): The names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.
  - `payees` (list of string): The names or the IDs of payees.
  - `projects` (list of string): The names or the IDs of projects. Their subprojects also match.
  - `tags` (list of string): The names or the IDs of tags. A row matches if it has one of the tags.
  - `kinds` (list of string): The kinds of transactions. Values: `income`, `expense`, `transfer`.
  - `min_amount` (string): The minimum amount, as a decimal number, in the currency of each row.
  - `max_amount` (string): The maximum amount, as a decimal number, in the currency of each row.
  - `currency` (string): The currency code of the rows, for example USD.
  - `text` (string): A text in the note or in the name of the payee.
  - `no_category` (boolean): True: only income and expense rows that have no category.
  - `status` (string): The reconcile status. Values: `unreconciled`, `cleared`, `reconciled`.
  - `planned` (boolean): True: only the rows that a plan made. False: only the other rows.
- `set` (object, required)
  - `kind` (string): The new kind, as the edit form of the app changes it. Income and expense: the category goes unless you give one of the new kind. To a transfer: give to_account (and to_amount for two currencies); the category, the payee, the project and the tags go. A transfer to an income or an expense keeps the row of the account that the money goes out of. A change to or from a transfer is only for one transaction. Values: `income`, `expense`, `transfer`.
  - `category` (string): The name, the path or the ID of the category. An empty text removes the category.
  - `payee` (string): The name or the ID of a payee that exists. An empty text removes the payee.
  - `project` (string): The name or the ID of the project. An empty text removes the project.
  - `tags` (list of string): The new list of tags. It replaces all the tags. An empty list removes all the tags.
  - `add_tags` (list of string): Tags to add. The other tags do not change.
  - `remove_tags` (list of string): Tags to remove. The other tags do not change.
  - `account` (string): The name or the ID of the account. For a transfer, the account that the money goes out of. An income or an expense can move only to an account with the same currency.
  - `to_account` (string): For a transfer: the account that the money goes into.
  - `date` (string): The new local date, YYYY-MM-DD, with a year from 1900 to 2100. The time of the day does not change.
  - `note` (string): The new note. An empty text removes the note.
  - `status` (string): The reconcile status. Values: `unreconciled`, `cleared`, `reconciled`.
  - `amount` (string): The new amount in the currency of the account. For a transfer, the amount that goes out. Only for one transaction.
  - `to_amount` (string): For a transfer between two currencies: the amount that goes into to_account, in its currency. Only for one transaction.
- `confirm` (string): The confirm token that the preview gave.

Output:

- `preview` (boolean): True if nothing changed yet: this is a preview.
- `change_id` (string or null, optional): After the change: to undo it, give this value to undo_change.
- `changes` (integer): The number of transactions that the call changes. In a preview, the number that it will change.
- `skipped` (list of object): The transactions that the call cannot change, with the reason. Not more than 20.
  - `id` (string)
  - `reason` (string)
- `confirm` (string or null, optional): To apply the change, call again with the same arguments and this token.
- `matches` (integer, optional): The number of transactions that ids or filter selects.
- `columns` (list of string, optional): The columns of examples, as in list_transactions.
- `examples` (list of list of any, optional): Not more than 20 of the transactions, before the change, as rows of list_transactions.
- `new` (any, optional): The new values of the fields.
- `effect` (object or null, optional): The income and the expense of the changed transactions before and after the change, in the base currency. Transfers are not included.
  - `base_currency` (string)
  - `rates` (object): The rates that the output used: the value of 1 unit of each currency in the base currency, as a decimal number. Only the currencies of the output; the base currency is not in it.
  - `rates_updated_at` (string or null): The time of the oldest rate in rates, or null when the output converts nothing.
  - `missing_rates` (list of string): The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
  - `before` (object)
    - `income` (string)
    - `expense` (string)
  - `after` (object)
    - `income` (string)
    - `expense` (string)
  - `by` (string): The type of group in groups.
  - `groups` (list of object): The groups that have different totals after the change. The largest change is first. Not more than 20.
    - `group` (string or null): The name of the group, or null for no value.
    - `before` (object)
      - `income` (string)
      - `expense` (string)
    - `after` (object)
      - `income` (string)
      - `expense` (string)
    - `missing_rates` (list of string): The currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.
  - `more_groups` (integer)

### `delete_transactions`: Delete transactions

Access: change. Deletes transactions that you select by IDs or by a filter (the two rows of a transfer). A planned transaction skips its date in the plan. When more than one transaction is deleted, the first call changes nothing and gives a preview with a confirm token: show the preview to the user, then call again with the same arguments and the token.

Input:

- `ids` (list of string): The IDs of the transactions, from list_transactions. Give ids or filter, not the two.
- `filter` (object): A filter with one or more conditions, as in list_transactions.
  - `from` (string): The first local date, YYYY-MM-DD. The range includes it.
  - `to` (string): The last local date, YYYY-MM-DD. The range includes it.
  - `accounts` (list of string): The names or the IDs of accounts. A transfer matches if one of its two accounts matches.
  - `categories` (list of string): The names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.
  - `payees` (list of string): The names or the IDs of payees.
  - `projects` (list of string): The names or the IDs of projects. Their subprojects also match.
  - `tags` (list of string): The names or the IDs of tags. A row matches if it has one of the tags.
  - `kinds` (list of string): The kinds of transactions. Values: `income`, `expense`, `transfer`.
  - `min_amount` (string): The minimum amount, as a decimal number, in the currency of each row.
  - `max_amount` (string): The maximum amount, as a decimal number, in the currency of each row.
  - `currency` (string): The currency code of the rows, for example USD.
  - `text` (string): A text in the note or in the name of the payee.
  - `no_category` (boolean): True: only income and expense rows that have no category.
  - `status` (string): The reconcile status. Values: `unreconciled`, `cleared`, `reconciled`.
  - `planned` (boolean): True: only the rows that a plan made. False: only the other rows.
- `confirm` (string): The confirm token that the preview gave.

Output:

- `preview` (boolean): True if nothing changed yet: this is a preview.
- `change_id` (string or null, optional): After the change: to undo it, give this value to undo_change.
- `changes` (integer): The number of transactions that the call changes. In a preview, the number that it will change.
- `skipped` (list of object): The transactions that the call cannot change, with the reason. Not more than 20.
  - `id` (string)
  - `reason` (string)
- `confirm` (string or null, optional): To apply the change, call again with the same arguments and this token.
- `matches` (integer, optional): The number of transactions that ids or filter selects.
- `columns` (list of string, optional): The columns of examples, as in list_transactions.
- `examples` (list of list of any, optional): Not more than 20 of the transactions, before the change, as rows of list_transactions.
- `new` (any, optional): The new values of the fields.
- `effect` (object or null, optional): The income and the expense of the changed transactions before and after the change, in the base currency. Transfers are not included.
  - `base_currency` (string)
  - `rates` (object): The rates that the output used: the value of 1 unit of each currency in the base currency, as a decimal number. Only the currencies of the output; the base currency is not in it.
  - `rates_updated_at` (string or null): The time of the oldest rate in rates, or null when the output converts nothing.
  - `missing_rates` (list of string): The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
  - `before` (object)
    - `income` (string)
    - `expense` (string)
  - `after` (object)
    - `income` (string)
    - `expense` (string)
  - `by` (string): The type of group in groups.
  - `groups` (list of object): The groups that have different totals after the change. The largest change is first. Not more than 20.
    - `group` (string or null): The name of the group, or null for no value.
    - `before` (object)
      - `income` (string)
      - `expense` (string)
    - `after` (object)
      - `income` (string)
      - `expense` (string)
    - `missing_rates` (list of string): The currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.
  - `more_groups` (integer)

### `update_settings`: Change the base currency

Access: change. Changes the base currency (the currency of the totals) and the second and the third currency of the balance, as the balance menu of the app. Accounts keep their currencies. The output gives the currencies that have no exchange rate to the new base currency.

Input:

- `base_currency` (string): The new base currency code, for example EUR. If the new one was the second or the third currency, the old base currency takes its place.
- `second_currency` (string): The currency code that the balance also shows, under the base currency. If it was the third currency and you do not give third_currency, the two change places. An empty text removes it, and the third currency becomes the second one.
- `third_currency` (string): The currency code that the balance shows after the second currency. Without a second currency, it becomes the second currency. An empty text removes it.

Output:

- `base_currency` (string)
- `rates` (object): The rates that the output used: the value of 1 unit of each currency in the base currency, as a decimal number. Only the currencies of the output; the base currency is not in it.
- `rates_updated_at` (string or null): The time of the oldest rate in rates, or null when the output converts nothing.
- `missing_rates` (list of string): The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
- `change_id` (string or null): To undo this call, give this value to undo_change. Null if nothing changed.
- `second_currency` (string or null)
- `third_currency` (string or null)

### `undo_change`: Undo a change

Access: change. Undoes one change of a write tool. With change_id, it undoes that change, also a change of another assistant of the same user: only the assistant that made the change gets its change_id, so the user must give it to you. If you do not give change_id, it undoes the last change of this assistant; when that change is already undone, nothing changes. Rows that changed after the change (for example on a device) do not change. An added item that a transaction or another item now uses stays.

Input:

- `change_id` (string): The change_id that a write call gave. It can be a change of another assistant of the same user. If you do not give it, the last change of this assistant is undone. When the last change is already undone, nothing changes.

Output:

- `change_id` (string)
- `restored` (integer): The number of rows that are now the same as before the change.
- `kept` (integer): The number of rows that a device or another call changed after the change. These rows do not change.

## Errors

A tool error starts with its code: `<code>: <message>`. An input that does not match the input schema gives an error of the MCP library, without a code.

- `invalid_input`: The input is not correct. The text of the error tells what to change.
- `not_found`: No account, account group, category, payee, project, tag, transaction or change has this name or ID. add_catalog_items can add a missing item.
- `ambiguous`: More than one item has this name. Ask the user which one, then give its ID.
- `conflict`: A device changed the data at the same time, or the data changed after the preview. Read the data again or make a new preview, then try again.
- `forbidden`: The user gave read access only. To change data, the user connects again and allows changes.
- `rate_limited`: Too many changes in one minute. Wait, then try again.
- `internal_error`: A server failure. Try again later.

HTTP errors of `/mcp`:

- `401`: no token, or the token expired. The client gets a new token or the person signs in again.
- `403`: MCP access is not available for this account yet.
- `429`: too many requests. Wait for the time in `Retry-After`.

## Limits

- Requests: 120 HTTP requests a minute for each user.
- Changes: 20 changes a minute for each user. A preview, a call that changes nothing and undo_change do not count.
- Page: 500 rows on a page of list_transactions (default 100).
- Add: 100 transactions in one add_transactions call, 100 items in one call of add_catalog_items, update_catalog_items or delete_catalog_items.
- Change: 5000 rows in one change (a transfer has two rows).
- Texts: 100 characters in a name, 1000 in a note or a description, as in the app.
- Dates: a written date has a year from 1900 to 2100.

## Technical details

- Endpoint: `POST https://never.malkindev.com/mcp`, stateless, JSON responses.
- Protected resource metadata: https://never.malkindev.com/.well-known/oauth-protected-resource/mcp
- Authorization server metadata: https://never.malkindev.com/.well-known/oauth-authorization-server
- Scopes: `ledger:read` (read tools), `ledger:write` (write tools). Each grant has `ledger:read`.
- Client registration: Client ID Metadata Document (an HTTPS URL as `client_id`) or dynamic client registration.
- PKCE with `S256` only. Refresh tokens rotate.
