NeverLose

Use NeverLose in your AI assistant.

Connect NeverLose to Claude, ChatGPT or any MCP client. Ask about your spending and balances, and let the assistant add and correct transactions, accounts and categories for you.

https://never.malkindev.com/mcp
ClaudeChatGPTClaude CodeCodexCursorVS CodeGemini CLI

Let your assistant set it up

Paste this into your assistant. It reads the docs and tells you each step.

Read https://never.malkindev.com/llms.txt and help me connect NeverLose. Then help me with my finances.

Docs for agents: llms.txt · docs.md

Connect

First, sign in to the NeverLose app with Google or Apple. Then use the same account on the web sign-in page.

Claude

  1. Open Customize → Connectors.
  2. Click + Add, then Add custom connector.
  3. Name: NeverLose. URL: https://never.malkindev.com/mcp. Click Add.
  4. Click Connect. Sign in with the Google or Apple account of your NeverLose app, then click Allow.
  5. 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.
  2. Add a custom MCP server. Name: NeverLose. URL: https://never.malkindev.com/mcp. Authentication: OAuth.
  3. Sign in with the Google or Apple account of your NeverLose app, then click Allow.
  4. 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.
  2. 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.
  2. 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.
  2. 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.
  2. In Gemini CLI, type /mcp auth neverlose and sign in.

Other

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

Examples

Click to copy, then paste into your assistant.

You stay in control

The assistant can do only what you allow.

Read or changeOn the sign-in page you choose: only read, or also add, change and delete data.
Preview firstA change or a delete of more than one transaction shows a preview. It applies only after you agree.
UndoEach change can be undone. Ask: “Undo the last change.”
DisconnectIn the app: Account → Assistants → Disconnect.

NeverLose keeps the records that you enter or that you ask your 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.

Tools

What the assistant can do. The server makes this list.

get_overviewread

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_currencystring
  • ratesobject

    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_atstring or null

    The time of the oldest rate in rates, or null when the output converts nothing.

  • missing_rateslist 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_currencystring or null

    The second currency of the balance in the app, or null.

  • third_currencystring or null

    The third currency of the balance in the app, or null.

  • has_accountsboolean

    False if the user has no accounts. Then add_transactions adds the first account.

  • account_groupslist of object

    The groups of the accounts, in the order of the app.

    • idstring
    • namestring
    • accountslist of string

      The IDs of the accounts in the group.

  • todaystring
  • time_zonestring
  • accountslist of object
    • idstring
    • namestring
    • typestring
    • currencystring
    • balancestring
    • balance_basestring or null

      The balance in the base currency, or null if there is no exchange rate.

    • in_totalboolean

      True if the total balance includes the account.

  • totalobject
    • amountstring

      The total balance of the accounts with in_total, in the base currency, without the currencies in missing_rates.

    • currencystring
  • transactionsinteger

    The number of transactions. A transfer is one transaction.

  • first_datestring or null

    The local date of the first transaction, or null if there are no transactions.

  • last_datestring or null

    The local date of the last transaction, or null if there are no transactions.

list_transactionsread

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

  • fromstring

    The first local date, YYYY-MM-DD. The range includes it.

  • tostring

    The last local date, YYYY-MM-DD. The range includes it.

  • accountslist of string

    The names or the IDs of accounts. A transfer matches if one of its two accounts matches.

  • categorieslist of string

    The names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.

  • payeeslist of string

    The names or the IDs of payees.

  • projectslist of string

    The names or the IDs of projects. Their subprojects also match.

  • tagslist of string

    The names or the IDs of tags. A row matches if it has one of the tags.

  • kindslist of string

    The kinds of transactions.

    incomeexpensetransfer
  • min_amountstring

    The minimum amount, as a decimal number, in the currency of each row.

  • max_amountstring

    The maximum amount, as a decimal number, in the currency of each row.

  • currencystring

    The currency code of the rows, for example USD.

  • textstring

    A text in the note or in the name of the payee.

  • no_categoryboolean

    True: only income and expense rows that have no category.

  • statusstring

    The reconcile status.

    unreconciledclearedreconciled
  • plannedboolean

    True: only the rows that a plan made. False: only the other rows.

  • limitinteger

    The number of rows on a page: 1 to 500. If you do not give it, 100.

  • cursorstring

    The next_cursor of the previous page.

Output

  • columnslist of string

    The names of the values in each row.

  • rowslist 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).

  • matchesinteger

    The number of transactions that match the filter, on all pages.

  • next_cursorstring or null

    To get the next page, give this value as cursor. It is null on the last page.

get_totalsread

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

  • fromstring

    The first local date, YYYY-MM-DD. The range includes it.

  • tostring

    The last local date, YYYY-MM-DD. The range includes it.

  • accountslist of string

    The names or the IDs of accounts. A transfer matches if one of its two accounts matches.

  • categorieslist of string

    The names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.

  • payeeslist of string

    The names or the IDs of payees.

  • projectslist of string

    The names or the IDs of projects. Their subprojects also match.

  • tagslist of string

    The names or the IDs of tags. A row matches if it has one of the tags.

  • kindslist of string

    The kinds of transactions.

    incomeexpensetransfer
  • min_amountstring

    The minimum amount, as a decimal number, in the currency of each row.

  • max_amountstring

    The maximum amount, as a decimal number, in the currency of each row.

  • currencystring

    The currency code of the rows, for example USD.

  • textstring

    A text in the note or in the name of the payee.

  • no_categoryboolean

    True: only income and expense rows that have no category.

  • statusstring

    The reconcile status.

    unreconciledclearedreconciled
  • plannedboolean

    True: only the rows that a plan made. False: only the other rows.

  • group_bylist of string

    The groups of the totals: zero, one or two values.

    categorypayeeprojectaccountmonth
  • limitinteger

    The maximum number of groups: 1 to 500. If you do not give it, 100.

Output

  • base_currencystring
  • ratesobject

    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_atstring or null

    The time of the oldest rate in rates, or null when the output converts nothing.

  • missing_rateslist 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_bylist of string
  • rowslist of object

    The groups. The list is empty if group_by is empty.

    • grouplist of string

      One value for each item of group_by. Null is for no value.

    • incomestring
    • expensestring
    • netstring
    • countinteger

      The number of transactions in the group.

    • missing_rateslist of string

      The currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.

  • incomestring
  • expensestring
  • netstring
  • countinteger

    The number of transactions.

  • more_groupsinteger

    The number of groups that are not shown because of the limit.

  • by_currencylist of object

    The income and the expense of all rows in each currency, before the conversion to the base currency.

    • currencystring
    • incomestring
    • expensestring
list_catalogread

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

  • kindstringrequired

    The type of items to list.

    account_groupsaccountscategoriespayeesprojectstags
  • querystring

    Only the names that contain this text. Upper case and lower case are the same.

  • limitinteger

    The maximum number of items: 1 to 500. If you do not give it, 200.

Output

  • kindstring
  • itemslist 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.

    • idstring
    • namestring
    • typestring or nulloptional

      For a category: income or expense. For an account: the type of the account.

    • pathstring or nulloptional

      For a subcategory: the path with the parent categories, for example Food / Cafe.

    • parentstring or nulloptional

      The name of the parent category or the parent project.

    • currencystring or nulloptional
    • colorstring or nulloptional

      The color as #RRGGBB.

    • iconstring or nulloptional

      For a category: the icon key.

    • favoritebooleanoptional

      True for a category that the user marked as a favorite.

    • builtinbooleanoptional

      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.

    • groupstring or nulloptional

      For an account: the name of its group.

    • in_balanceboolean or nulloptional

      For an account: true if the total balance includes it.

    • initial_balancestring or nulloptional

      For an account: the balance before all transactions.

    • balancestring or nulloptional

      For an account: the balance now.

    • accountslist of stringoptional

      For an account group: the IDs of its accounts.

    • statusstring or nulloptional

      For a project: active or inactive.

    • limitstring or nulloptional

      For a project: the budget, in the currency of the project.

    • datestring or nulloptional

      For a project: the local date.

    • descriptionstring or nulloptional

      For a project: the note.

    • categorystring or nulloptional

      For a payee: the category (a path) that a new transaction with the payee gets.

    • projectstring or nulloptional

      For a payee: the project that a new transaction with the payee gets.

    • tagslist of stringoptional

      For a payee: the tags that a new transaction with the payee gets.

    • countinteger

      The number of transaction rows that use the item. For an account group: the number of its accounts.

  • moreinteger

    The number of items that are not shown because of the limit.

add_transactionswrite

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

  • transactionslist of objectrequired

    The transactions to add: 1 to 100.

    • request_idstring

      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.

    • kindstringrequired

      The kind of the transaction.

      incomeexpensetransfer
    • datestring

      The local date, YYYY-MM-DD, with a year from 1900 to 2100. If you do not give it, the date is today.

    • accountstringrequired

      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.

    • amountstringrequired

      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_accountstring

      For a transfer: the account that the money goes into.

    • to_amountstring

      For a transfer between two currencies: the amount that goes into to_account, in its currency.

    • categorystring

      The name, the path or the ID of the category. The type of the category must be the same as the kind.

    • payeestring

      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.

    • projectstring

      The name or the ID of the project.

    • tagslist of string

      The names or the IDs of the tags.

    • notestring

      A note.

    • statusstring

      The reconcile status. If you do not give it: unreconciled for an income or an expense with a date after today, else reconciled.

      unreconciledclearedreconciled

Output

  • change_idstring or null

    To undo this call, give this value to undo_change.

  • addedinteger
  • idslist of string

    The ID of each transaction, in the order of the input.

  • new_payeeslist of string

    The names of the payees that the call added.

  • new_accountslist of string

    The names of the accounts that the call added. Only a user with no accounts gets a new account.

  • already_addedinteger

    The number of rows that an earlier call with the same request_id added. These rows are not added again.

add_catalog_itemswrite

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_groupslist of object

    New groups of accounts.

    • namestringrequired

      The name of the group.

  • accountslist of object

    New accounts.

    • namestringrequired

      The name of the account.

    • currencystring

      The currency code, for example EUR. If you do not give it, the base currency.

    • typestring

      The type of the account. If you do not give it, bank.

      cashbankassetcreditCarddebitCardinvestmentliabilityloanreceivabletaxLiability
    • groupstring

      The name or the ID of the account group. If you do not give it, Cards and accounts.

    • balancestring

      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_balanceboolean

      False: the total balance does not include the account. If you do not give it, true.

    • colorstring

      The color as #RRGGBB.

  • categorieslist of object

    New categories and subcategories.

    • namestringrequired

      The name of the category, without the parent.

    • typestring

      The type of the category. If you do not give it, expense. A subcategory has the type of its parent.

      expenseincome
    • parentstring

      For a subcategory: the name or the ID of a top-level category. A subcategory cannot have subcategories.

    • iconstring

      The icon key. If you do not give it, the icon of the parent, else unknown.

      alienbackhoebiohazardbookbrightnesscarcashghostgiftgrocerieshealthhomekitchenlaptopscootershirtsuntinderunknownvirusmat:directions_carmat:local_car_washmat:buildmat:local_gas_stationmat:local_parkingmat:local_taximat:directions_busmat:directions_bikemat:directions_transitmat:business_centermat:workmat:apartmentmat:calculatemat:badgemat:devicesmat:desktop_macmat:receipt_longmat:receiptmat:shieldmat:gavelmat:paymentsmat:attach_moneymat:account_balancemat:account_balance_walletmat:child_caremat:family_restroommat:child_friendlymat:schoolmat:sports_soccermat:sports_basketballmat:checkroommat:toysmat:homemat:grassmat:water_dropmat:electric_boltmat:boltmat:local_fire_departmentmat:cleaning_servicesmat:wifimat:phone_androidmat:tvmat:volunteer_activismmat:petsmat:local_hospitalmat:medical_servicesmat:local_pharmacymat:fitness_centermat:spamat:local_laundry_servicemat:content_cutmat:health_and_safetymat:restaurantmat:local_cafemat:local_barmat:local_grocery_storemat:shopping_bagmat:shopping_cartmat:card_giftcardmat:flightmat:flight_takeoffmat:hotelmat:museummat:sim_cardmat:moviemat:subscriptionsmat:savingsmat:bar_chartmat:trending_downmat:storefrontmat:campaignmat:menu_bookmat:handymanmat:outdoor_grillmat:hikingmat:nature_peoplemat:sellmat:request_quotemat:money_offmat:favoritemat:star
    • colorstring

      The color as #RRGGBB.

  • projectslist of object

    New projects.

    • namestringrequired

      The name of the project.

    • descriptionstring

      A note about the project.

    • statusstring

      The status of the project. If you do not give it, active.

      activeinactive
    • currencystring

      The currency code of the limit. If you do not give it, the base currency.

    • limitstring

      The budget of the project in its currency, as a decimal number with a point.

    • datestring

      The local date of the project, YYYY-MM-DD. If you do not give it, today.

    • parentstring

      The name or the ID of the parent project.

  • payeeslist of object

    New payees.

    • namestringrequired

      The name of the payee.

    • categorystring

      The category that a new transaction with this payee gets: a name, a path or an ID.

    • projectstring

      The project that a new transaction with this payee gets.

    • tagslist of string

      The tags that a new transaction with this payee gets.

  • tagslist of object

    New tags.

    • namestringrequired

      The name of the tag.

    • colorstring

      The color as #RRGGBB.

Output

  • change_idstring or null

    To undo this call, give this value to undo_change. Null if the call added nothing.

  • createdlist of object

    The items that the call added.

    • kindstring

      The list of the item, as the kind of list_catalog.

    • idstring
    • namestring

      The name. For a subcategory, the path, for example Food / Cafe.

  • existinglist of object

    The items that already had the name. The call did not add or change them.

    • kindstring

      The list of the item, as the kind of list_catalog.

    • idstring
    • namestring

      The name. For a subcategory, the path, for example Food / Cafe.

update_catalog_itemschange

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_groupslist of object

    Changes of account groups.

    • refstringrequired

      The name or the ID of the group.

    • namestring

      The new name.

    • positioninteger

      The new place of the group in the list, from 1. The other groups move.

  • accountslist of object

    Changes of accounts.

    • refstringrequired

      The name or the ID of the account.

    • namestring

      The new name.

    • typestring

      The type of the account.

      cashbankassetcreditCarddebitCardinvestmentliabilityloanreceivabletaxLiability
    • groupstring

      The name or the ID of the account group.

    • balancestring

      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_balanceboolean

      False: the total balance does not include the account.

    • colorstring

      The color as #RRGGBB.

    • currencystring

      The currency code. Only an account without transactions and plans can change its currency.

  • categorieslist of object

    Changes of categories.

    • refstringrequired

      The name, the path or the ID of the category.

    • namestring

      The new name, without the parent.

    • parentstring

      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.

    • iconstring

      The icon key.

      alienbackhoebiohazardbookbrightnesscarcashghostgiftgrocerieshealthhomekitchenlaptopscootershirtsuntinderunknownvirusmat:directions_carmat:local_car_washmat:buildmat:local_gas_stationmat:local_parkingmat:local_taximat:directions_busmat:directions_bikemat:directions_transitmat:business_centermat:workmat:apartmentmat:calculatemat:badgemat:devicesmat:desktop_macmat:receipt_longmat:receiptmat:shieldmat:gavelmat:paymentsmat:attach_moneymat:account_balancemat:account_balance_walletmat:child_caremat:family_restroommat:child_friendlymat:schoolmat:sports_soccermat:sports_basketballmat:checkroommat:toysmat:homemat:grassmat:water_dropmat:electric_boltmat:boltmat:local_fire_departmentmat:cleaning_servicesmat:wifimat:phone_androidmat:tvmat:volunteer_activismmat:petsmat:local_hospitalmat:medical_servicesmat:local_pharmacymat:fitness_centermat:spamat:local_laundry_servicemat:content_cutmat:health_and_safetymat:restaurantmat:local_cafemat:local_barmat:local_grocery_storemat:shopping_bagmat:shopping_cartmat:card_giftcardmat:flightmat:flight_takeoffmat:hotelmat:museummat:sim_cardmat:moviemat:subscriptionsmat:savingsmat:bar_chartmat:trending_downmat:storefrontmat:campaignmat:menu_bookmat:handymanmat:outdoor_grillmat:hikingmat:nature_peoplemat:sellmat:request_quotemat:money_offmat:favoritemat:star
    • colorstring

      The color as #RRGGBB.

    • favoriteboolean

      True: the app shows the category in the favorites group. False: it does not.

  • projectslist of object

    Changes of projects.

    • refstringrequired

      The name or the ID of the project.

    • namestring

      The new name.

    • descriptionstring

      A note about the project.

    • statusstring

      The status of the project.

      activeinactive
    • currencystring

      The currency code of the limit. Without a new limit, the limit keeps its number.

    • limitstring

      The budget in the currency of the project, as a decimal number with a point. An empty text removes the limit.

    • datestring

      The local date of the project, YYYY-MM-DD.

    • parentstring

      The name or the ID of the parent project. An empty text makes it a top-level project.

  • payeeslist of object

    Changes of payees.

    • refstringrequired

      The name or the ID of the payee.

    • namestring

      The new name.

    • categorystring

      The category that a new transaction with this payee gets. An empty text removes it.

    • projectstring

      The project that a new transaction with this payee gets. An empty text removes it.

    • tagslist of string

      The tags that a new transaction with this payee gets. They replace the tags. An empty list removes them.

  • tagslist of object

    Changes of tags.

    • refstringrequired

      The name or the ID of the tag.

    • namestring

      The new name.

    • colorstring

      The color as #RRGGBB.

  • confirmstring

    The confirm token that the preview gave.

Output

  • previewboolean

    True if nothing changed yet: this is a preview.

  • change_idstring or nulloptional

    After the change: to undo it, give this value to undo_change.

  • itemslist of object

    The items of the input and what the call does to them.

    • kindstring

      The list of the item, as the kind of list_catalog.

    • idstring
    • namestring
    • actionstring

      changed, deleted or merged.

    • intoobject or nulloptional

      For a merged item: the item that got its uses.

      • kindstring

        The list of the item, as the kind of list_catalog.

      • idstring
      • namestring

        The name. For a subcategory, the path, for example Food / Cafe.

  • rowslist of object

    The number of rows of each kind that the call changes or deletes, the items included.

    • kindstring

      The kind of the rows, for example transactions or planner_plans.

    • changedinteger
    • deletedinteger
  • confirmstring or nulloptional

    To apply the change, call again with the same arguments and this token.

  • effectobject or nulloptional

    In a preview: the income and the expense of the changed transactions before and after the change, in the base currency.

    • base_currencystring
    • ratesobject

      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_atstring or null

      The time of the oldest rate in rates, or null when the output converts nothing.

    • missing_rateslist of string

      The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.

    • beforeobject
      • incomestring
      • expensestring
    • afterobject
      • incomestring
      • expensestring
    • bystring

      The type of group in groups.

    • groupslist of object

      The groups that have different totals after the change. The largest change is first. Not more than 20.

      • groupstring or null

        The name of the group, or null for no value.

      • beforeobject
        • incomestring
        • expensestring
      • afterobject
        • incomestring
        • expensestring
      • missing_rateslist of string

        The currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.

    • more_groupsinteger
delete_catalog_itemschange

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_groupslist of object

    Account groups to delete.

    • refstringrequired

      The name or the ID of the group. Its accounts move to the first group. The last group cannot be deleted.

  • accountslist of object

    Accounts to delete.

    • refstringrequired

      The name or the ID of the account. The plans of the account are deleted too.

    • transactionsstring

      keep: the transactions stay, as in the app. delete: the transactions of the account are deleted too. If you do not give it, keep.

      keepdelete
  • categorieslist of object

    Categories to delete or merge. Transactions, plans and payees lose a deleted category; its subcategories become top-level categories.

    • refstringrequired

      The name or the ID of the item.

    • merge_intostring

      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.

  • projectslist of object

    Projects to delete or merge.

    • refstringrequired

      The name or the ID of the item.

    • merge_intostring

      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.

  • payeeslist of object

    Payees to delete or merge.

    • refstringrequired

      The name or the ID of the item.

    • merge_intostring

      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.

  • tagslist of object

    Tags to delete or merge.

    • refstringrequired

      The name or the ID of the item.

    • merge_intostring

      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.

  • confirmstring

    The confirm token that the preview gave.

Output

  • previewboolean

    True if nothing changed yet: this is a preview.

  • change_idstring or nulloptional

    After the change: to undo it, give this value to undo_change.

  • itemslist of object

    The items of the input and what the call does to them.

    • kindstring

      The list of the item, as the kind of list_catalog.

    • idstring
    • namestring
    • actionstring

      changed, deleted or merged.

    • intoobject or nulloptional

      For a merged item: the item that got its uses.

      • kindstring

        The list of the item, as the kind of list_catalog.

      • idstring
      • namestring

        The name. For a subcategory, the path, for example Food / Cafe.

  • rowslist of object

    The number of rows of each kind that the call changes or deletes, the items included.

    • kindstring

      The kind of the rows, for example transactions or planner_plans.

    • changedinteger
    • deletedinteger
  • confirmstring or nulloptional

    To apply the change, call again with the same arguments and this token.

  • effectobject or nulloptional

    In a preview: the income and the expense of the changed transactions before and after the change, in the base currency.

    • base_currencystring
    • ratesobject

      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_atstring or null

      The time of the oldest rate in rates, or null when the output converts nothing.

    • missing_rateslist of string

      The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.

    • beforeobject
      • incomestring
      • expensestring
    • afterobject
      • incomestring
      • expensestring
    • bystring

      The type of group in groups.

    • groupslist of object

      The groups that have different totals after the change. The largest change is first. Not more than 20.

      • groupstring or null

        The name of the group, or null for no value.

      • beforeobject
        • incomestring
        • expensestring
      • afterobject
        • incomestring
        • expensestring
      • missing_rateslist of string

        The currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.

    • more_groupsinteger
update_transactionschange

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

  • idslist of string

    The IDs of the transactions, from list_transactions. Give ids or filter, not the two.

  • filterobject

    A filter with one or more conditions, as in list_transactions.

    • fromstring

      The first local date, YYYY-MM-DD. The range includes it.

    • tostring

      The last local date, YYYY-MM-DD. The range includes it.

    • accountslist of string

      The names or the IDs of accounts. A transfer matches if one of its two accounts matches.

    • categorieslist of string

      The names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.

    • payeeslist of string

      The names or the IDs of payees.

    • projectslist of string

      The names or the IDs of projects. Their subprojects also match.

    • tagslist of string

      The names or the IDs of tags. A row matches if it has one of the tags.

    • kindslist of string

      The kinds of transactions.

      incomeexpensetransfer
    • min_amountstring

      The minimum amount, as a decimal number, in the currency of each row.

    • max_amountstring

      The maximum amount, as a decimal number, in the currency of each row.

    • currencystring

      The currency code of the rows, for example USD.

    • textstring

      A text in the note or in the name of the payee.

    • no_categoryboolean

      True: only income and expense rows that have no category.

    • statusstring

      The reconcile status.

      unreconciledclearedreconciled
    • plannedboolean

      True: only the rows that a plan made. False: only the other rows.

  • setobjectrequired
    • kindstring

      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.

      incomeexpensetransfer
    • categorystring

      The name, the path or the ID of the category. An empty text removes the category.

    • payeestring

      The name or the ID of a payee that exists. An empty text removes the payee.

    • projectstring

      The name or the ID of the project. An empty text removes the project.

    • tagslist of string

      The new list of tags. It replaces all the tags. An empty list removes all the tags.

    • add_tagslist of string

      Tags to add. The other tags do not change.

    • remove_tagslist of string

      Tags to remove. The other tags do not change.

    • accountstring

      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_accountstring

      For a transfer: the account that the money goes into.

    • datestring

      The new local date, YYYY-MM-DD, with a year from 1900 to 2100. The time of the day does not change.

    • notestring

      The new note. An empty text removes the note.

    • statusstring

      The reconcile status.

      unreconciledclearedreconciled
    • amountstring

      The new amount in the currency of the account. For a transfer, the amount that goes out. Only for one transaction.

    • to_amountstring

      For a transfer between two currencies: the amount that goes into to_account, in its currency. Only for one transaction.

  • confirmstring

    The confirm token that the preview gave.

Output

  • previewboolean

    True if nothing changed yet: this is a preview.

  • change_idstring or nulloptional

    After the change: to undo it, give this value to undo_change.

  • changesinteger

    The number of transactions that the call changes. In a preview, the number that it will change.

  • skippedlist of object

    The transactions that the call cannot change, with the reason. Not more than 20.

    • idstring
    • reasonstring
  • confirmstring or nulloptional

    To apply the change, call again with the same arguments and this token.

  • matchesintegeroptional

    The number of transactions that ids or filter selects.

  • columnslist of stringoptional

    The columns of examples, as in list_transactions.

  • exampleslist of list of anyoptional

    Not more than 20 of the transactions, before the change, as rows of list_transactions.

  • newanyoptional

    The new values of the fields.

  • effectobject or nulloptional

    The income and the expense of the changed transactions before and after the change, in the base currency. Transfers are not included.

    • base_currencystring
    • ratesobject

      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_atstring or null

      The time of the oldest rate in rates, or null when the output converts nothing.

    • missing_rateslist of string

      The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.

    • beforeobject
      • incomestring
      • expensestring
    • afterobject
      • incomestring
      • expensestring
    • bystring

      The type of group in groups.

    • groupslist of object

      The groups that have different totals after the change. The largest change is first. Not more than 20.

      • groupstring or null

        The name of the group, or null for no value.

      • beforeobject
        • incomestring
        • expensestring
      • afterobject
        • incomestring
        • expensestring
      • missing_rateslist of string

        The currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.

    • more_groupsinteger
delete_transactionschange

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

  • idslist of string

    The IDs of the transactions, from list_transactions. Give ids or filter, not the two.

  • filterobject

    A filter with one or more conditions, as in list_transactions.

    • fromstring

      The first local date, YYYY-MM-DD. The range includes it.

    • tostring

      The last local date, YYYY-MM-DD. The range includes it.

    • accountslist of string

      The names or the IDs of accounts. A transfer matches if one of its two accounts matches.

    • categorieslist of string

      The names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.

    • payeeslist of string

      The names or the IDs of payees.

    • projectslist of string

      The names or the IDs of projects. Their subprojects also match.

    • tagslist of string

      The names or the IDs of tags. A row matches if it has one of the tags.

    • kindslist of string

      The kinds of transactions.

      incomeexpensetransfer
    • min_amountstring

      The minimum amount, as a decimal number, in the currency of each row.

    • max_amountstring

      The maximum amount, as a decimal number, in the currency of each row.

    • currencystring

      The currency code of the rows, for example USD.

    • textstring

      A text in the note or in the name of the payee.

    • no_categoryboolean

      True: only income and expense rows that have no category.

    • statusstring

      The reconcile status.

      unreconciledclearedreconciled
    • plannedboolean

      True: only the rows that a plan made. False: only the other rows.

  • confirmstring

    The confirm token that the preview gave.

Output

  • previewboolean

    True if nothing changed yet: this is a preview.

  • change_idstring or nulloptional

    After the change: to undo it, give this value to undo_change.

  • changesinteger

    The number of transactions that the call changes. In a preview, the number that it will change.

  • skippedlist of object

    The transactions that the call cannot change, with the reason. Not more than 20.

    • idstring
    • reasonstring
  • confirmstring or nulloptional

    To apply the change, call again with the same arguments and this token.

  • matchesintegeroptional

    The number of transactions that ids or filter selects.

  • columnslist of stringoptional

    The columns of examples, as in list_transactions.

  • exampleslist of list of anyoptional

    Not more than 20 of the transactions, before the change, as rows of list_transactions.

  • newanyoptional

    The new values of the fields.

  • effectobject or nulloptional

    The income and the expense of the changed transactions before and after the change, in the base currency. Transfers are not included.

    • base_currencystring
    • ratesobject

      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_atstring or null

      The time of the oldest rate in rates, or null when the output converts nothing.

    • missing_rateslist of string

      The currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.

    • beforeobject
      • incomestring
      • expensestring
    • afterobject
      • incomestring
      • expensestring
    • bystring

      The type of group in groups.

    • groupslist of object

      The groups that have different totals after the change. The largest change is first. Not more than 20.

      • groupstring or null

        The name of the group, or null for no value.

      • beforeobject
        • incomestring
        • expensestring
      • afterobject
        • incomestring
        • expensestring
      • missing_rateslist of string

        The currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.

    • more_groupsinteger
update_settingschange

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_currencystring

    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_currencystring

    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_currencystring

    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_currencystring
  • ratesobject

    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_atstring or null

    The time of the oldest rate in rates, or null when the output converts nothing.

  • missing_rateslist 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_idstring or null

    To undo this call, give this value to undo_change. Null if nothing changed.

  • second_currencystring or null
  • third_currencystring or null
undo_changechange

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_idstring

    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_idstring
  • restoredinteger

    The number of rows that are now the same as before the change.

  • keptinteger

    The number of rows that a device or another call changed after the change. These rows do not change.

Rules for assistants

NeverLose is a personal finance app. These tools read and change the data of the user. The server gives these rules to each assistant.

  • 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

AmountA 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".
DateYYYY-MM-DD: a local date in the time zone of the user. A range includes both dates.
MonthYYYY-MM, in the month groups of get_totals.
TimeRFC 3339 in UTC, for example rates_updated_at.
NameAccount 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.

Errors

A tool error starts with its code: code: message.

invalid_inputThe input is not correct. The text of the error tells what to change.
not_foundNo account, account group, category, payee, project, tag, transaction or change has this name or ID. add_catalog_items can add a missing item.
ambiguousMore than one item has this name. Ask the user which one, then give its ID.
conflictA 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.
forbiddenThe user gave read access only. To change data, the user connects again and allows changes.
rate_limitedToo many changes in one minute. Wait, then try again.
internal_errorA server failure. Try again later.

Limits

For each user.

Requests120 HTTP requests a minute for each user
Changes20 changes a minute for each user. A preview, a call that changes nothing and undo_change do not count
Page500 rows on a page of list_transactions (default 100)
Add100 transactions in one add_transactions call, 100 items in one call of add_catalog_items, update_catalog_items or delete_catalog_items
Change5000 rows in one change (a transfer has two rows)
Texts100 characters in a name, 1000 in a note or a description, as in the app
Datesa written date has a year from 1900 to 2100

Technical details

For developers of MCP clients.

Endpoint
POST https://never.malkindev.com/mcp · Streamable HTTP, stateless, JSON responses
Authorization
OAuth 2.1, PKCE with S256, refresh tokens rotate
Client registration
Client ID Metadata Document (an HTTPS URL as client_id) or dynamic client registration
Scopes
ledger:read for the read tools, ledger:write for the write tools
Metadata
https://never.malkindev.com/.well-known/oauth-protected-resource/mcp
https://never.malkindev.com/.well-known/oauth-authorization-server