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/mcpConnect
First, sign in to the NeverLose app with Google or Apple. Then use the same account on the web sign-in page.
Claude
- Open Customize → Connectors.
- Click + Add, then Add custom connector.
- Name: NeverLose. URL: https://never.malkindev.com/mcp. Click Add.
- Click Connect. Sign in with the Google or Apple account of your NeverLose app, then click Allow.
- 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
- Turn on Developer mode: Settings → Apps → Advanced settings.
- Add a custom MCP server. Name: NeverLose. URL: https://never.malkindev.com/mcp. Authentication: OAuth.
- Sign in with the Google or Apple account of your NeverLose app, then click Allow.
- 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- Run the command.
- 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- Run the commands. The second command opens the sign-in page.
Cursor
{
"mcpServers": {
"neverlose": { "url": "https://never.malkindev.com/mcp" }
}
}- Add this to ~/.cursor/mcp.json.
- 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"}'- Run the command.
- 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- Run the command.
- In Gemini CLI, type /mcp auth neverlose and sign in.
Other
- Use a client that supports remote MCP servers (Streamable HTTP) with OAuth.
- Give it the URL https://never.malkindev.com/mcp.
- 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.
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.
get_overviewreadInput
No input.
Output
base_currencystringratesobjectThe 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 nullThe time of the oldest rate in rates, or null when the output converts nothing.
missing_rateslist of stringThe currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
second_currencystring or nullThe second currency of the balance in the app, or null.
third_currencystring or nullThe third currency of the balance in the app, or null.
has_accountsbooleanFalse if the user has no accounts. Then add_transactions adds the first account.
account_groupslist of objectThe groups of the accounts, in the order of the app.
idstringnamestringaccountslist of stringThe IDs of the accounts in the group.
todaystringtime_zonestringaccountslist of objectidstringnamestringtypestringcurrencystringbalancestringbalance_basestring or nullThe balance in the base currency, or null if there is no exchange rate.
in_totalbooleanTrue if the total balance includes the account.
totalobjectamountstringThe total balance of the accounts with in_total, in the base currency, without the currencies in missing_rates.
currencystring
transactionsintegerThe number of transactions. A transfer is one transaction.
first_datestring or nullThe local date of the first transaction, or null if there are no transactions.
last_datestring or nullThe 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.
list_transactionsreadInput
fromstringThe first local date, YYYY-MM-DD. The range includes it.
tostringThe last local date, YYYY-MM-DD. The range includes it.
accountslist of stringThe names or the IDs of accounts. A transfer matches if one of its two accounts matches.
categorieslist of stringThe names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.
payeeslist of stringThe names or the IDs of payees.
projectslist of stringThe names or the IDs of projects. Their subprojects also match.
tagslist of stringThe names or the IDs of tags. A row matches if it has one of the tags.
kindslist of stringThe kinds of transactions.
incomeexpensetransfermin_amountstringThe minimum amount, as a decimal number, in the currency of each row.
max_amountstringThe maximum amount, as a decimal number, in the currency of each row.
currencystringThe currency code of the rows, for example USD.
textstringA text in the note or in the name of the payee.
no_categorybooleanTrue: only income and expense rows that have no category.
statusstringThe reconcile status.
unreconciledclearedreconciledplannedbooleanTrue: only the rows that a plan made. False: only the other rows.
limitintegerThe number of rows on a page: 1 to 500. If you do not give it, 100.
cursorstringThe next_cursor of the previous page.
Output
columnslist of stringThe names of the values in each row.
rowslist of list of anyEach 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).
matchesintegerThe number of transactions that match the filter, on all pages.
next_cursorstring or nullTo 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.
get_totalsreadInput
fromstringThe first local date, YYYY-MM-DD. The range includes it.
tostringThe last local date, YYYY-MM-DD. The range includes it.
accountslist of stringThe names or the IDs of accounts. A transfer matches if one of its two accounts matches.
categorieslist of stringThe names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.
payeeslist of stringThe names or the IDs of payees.
projectslist of stringThe names or the IDs of projects. Their subprojects also match.
tagslist of stringThe names or the IDs of tags. A row matches if it has one of the tags.
kindslist of stringThe kinds of transactions.
incomeexpensetransfermin_amountstringThe minimum amount, as a decimal number, in the currency of each row.
max_amountstringThe maximum amount, as a decimal number, in the currency of each row.
currencystringThe currency code of the rows, for example USD.
textstringA text in the note or in the name of the payee.
no_categorybooleanTrue: only income and expense rows that have no category.
statusstringThe reconcile status.
unreconciledclearedreconciledplannedbooleanTrue: only the rows that a plan made. False: only the other rows.
group_bylist of stringThe groups of the totals: zero, one or two values.
categorypayeeprojectaccountmonthlimitintegerThe maximum number of groups: 1 to 500. If you do not give it, 100.
Output
base_currencystringratesobjectThe 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 nullThe time of the oldest rate in rates, or null when the output converts nothing.
missing_rateslist of stringThe currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
group_bylist of stringrowslist of objectThe groups. The list is empty if group_by is empty.
grouplist of stringOne value for each item of group_by. Null is for no value.
incomestringexpensestringnetstringcountintegerThe number of transactions in the group.
missing_rateslist of stringThe currencies of the group that have no exchange rate. Their amounts are not included in the totals of the group.
incomestringexpensestringnetstringcountintegerThe number of transactions.
more_groupsintegerThe number of groups that are not shown because of the limit.
by_currencylist of objectThe income and the expense of all rows in each currency, before the conversion to the base currency.
currencystringincomestringexpensestring
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.
list_catalogreadInput
kindstringrequiredThe type of items to list.
account_groupsaccountscategoriespayeesprojectstagsquerystringOnly the names that contain this text. Upper case and lower case are the same.
limitintegerThe maximum number of items: 1 to 500. If you do not give it, 200.
Output
kindstringitemslist of objectThe items. Account groups are in the order of the app. For the other kinds, the item that is used most is first.
idstringnamestringtypestring or nulloptionalFor a category: income or expense. For an account: the type of the account.
pathstring or nulloptionalFor a subcategory: the path with the parent categories, for example Food / Cafe.
parentstring or nulloptionalThe name of the parent category or the parent project.
currencystring or nulloptionalcolorstring or nulloptionalThe color as #RRGGBB.
iconstring or nulloptionalFor a category: the icon key.
favoritebooleanoptionalTrue for a category that the user marked as a favorite.
builtinbooleanoptionalTrue 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 nulloptionalFor an account: the name of its group.
in_balanceboolean or nulloptionalFor an account: true if the total balance includes it.
initial_balancestring or nulloptionalFor an account: the balance before all transactions.
balancestring or nulloptionalFor an account: the balance now.
accountslist of stringoptionalFor an account group: the IDs of its accounts.
statusstring or nulloptionalFor a project: active or inactive.
limitstring or nulloptionalFor a project: the budget, in the currency of the project.
datestring or nulloptionalFor a project: the local date.
descriptionstring or nulloptionalFor a project: the note.
categorystring or nulloptionalFor a payee: the category (a path) that a new transaction with the payee gets.
projectstring or nulloptionalFor a payee: the project that a new transaction with the payee gets.
tagslist of stringoptionalFor a payee: the tags that a new transaction with the payee gets.
countintegerThe number of transaction rows that use the item. For an account group: the number of its accounts.
moreintegerThe 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.
add_transactionswriteInput
transactionslist of objectrequiredThe transactions to add: 1 to 100.
request_idstringA 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.
kindstringrequiredThe kind of the transaction.
incomeexpensetransferdatestringThe local date, YYYY-MM-DD, with a year from 1900 to 2100. If you do not give it, the date is today.
accountstringrequiredThe 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.
amountstringrequiredThe 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_accountstringFor a transfer: the account that the money goes into.
to_amountstringFor a transfer between two currencies: the amount that goes into to_account, in its currency.
categorystringThe name, the path or the ID of the category. The type of the category must be the same as the kind.
payeestringThe 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.
projectstringThe name or the ID of the project.
tagslist of stringThe names or the IDs of the tags.
notestringA note.
statusstringThe 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 nullTo undo this call, give this value to undo_change.
addedintegeridslist of stringThe ID of each transaction, in the order of the input.
new_payeeslist of stringThe names of the payees that the call added.
new_accountslist of stringThe names of the accounts that the call added. Only a user with no accounts gets a new account.
already_addedintegerThe 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.
add_catalog_itemswriteInput
account_groupslist of objectNew groups of accounts.
namestringrequiredThe name of the group.
accountslist of objectNew accounts.
namestringrequiredThe name of the account.
currencystringThe currency code, for example EUR. If you do not give it, the base currency.
typestringThe type of the account. If you do not give it, bank.
cashbankassetcreditCarddebitCardinvestmentliabilityloanreceivabletaxLiabilitygroupstringThe name or the ID of the account group. If you do not give it, Cards and accounts.
balancestringThe 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_balancebooleanFalse: the total balance does not include the account. If you do not give it, true.
colorstringThe color as #RRGGBB.
categorieslist of objectNew categories and subcategories.
namestringrequiredThe name of the category, without the parent.
typestringThe type of the category. If you do not give it, expense. A subcategory has the type of its parent.
expenseincomeparentstringFor a subcategory: the name or the ID of a top-level category. A subcategory cannot have subcategories.
iconstringThe 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:starcolorstringThe color as #RRGGBB.
projectslist of objectNew projects.
namestringrequiredThe name of the project.
descriptionstringA note about the project.
statusstringThe status of the project. If you do not give it, active.
activeinactivecurrencystringThe currency code of the limit. If you do not give it, the base currency.
limitstringThe budget of the project in its currency, as a decimal number with a point.
datestringThe local date of the project, YYYY-MM-DD. If you do not give it, today.
parentstringThe name or the ID of the parent project.
payeeslist of objectNew payees.
namestringrequiredThe name of the payee.
categorystringThe category that a new transaction with this payee gets: a name, a path or an ID.
projectstringThe project that a new transaction with this payee gets.
tagslist of stringThe tags that a new transaction with this payee gets.
tagslist of objectNew tags.
namestringrequiredThe name of the tag.
colorstringThe color as #RRGGBB.
Output
change_idstring or nullTo undo this call, give this value to undo_change. Null if the call added nothing.
createdlist of objectThe items that the call added.
kindstringThe list of the item, as the kind of list_catalog.
idstringnamestringThe name. For a subcategory, the path, for example Food / Cafe.
existinglist of objectThe items that already had the name. The call did not add or change them.
kindstringThe list of the item, as the kind of list_catalog.
idstringnamestringThe 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.
update_catalog_itemschangeInput
account_groupslist of objectChanges of account groups.
refstringrequiredThe name or the ID of the group.
namestringThe new name.
positionintegerThe new place of the group in the list, from 1. The other groups move.
accountslist of objectChanges of accounts.
refstringrequiredThe name or the ID of the account.
namestringThe new name.
typestringThe type of the account.
cashbankassetcreditCarddebitCardinvestmentliabilityloanreceivabletaxLiabilitygroupstringThe name or the ID of the account group.
balancestringThe 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_balancebooleanFalse: the total balance does not include the account.
colorstringThe color as #RRGGBB.
currencystringThe currency code. Only an account without transactions and plans can change its currency.
categorieslist of objectChanges of categories.
refstringrequiredThe name, the path or the ID of the category.
namestringThe new name, without the parent.
parentstringA top-level category of the same type. An empty text makes it a top-level category. The type of a category does not change.
iconstringThe 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:starcolorstringThe color as #RRGGBB.
favoritebooleanTrue: the app shows the category in the favorites group. False: it does not.
projectslist of objectChanges of projects.
refstringrequiredThe name or the ID of the project.
namestringThe new name.
descriptionstringA note about the project.
statusstringThe status of the project.
activeinactivecurrencystringThe currency code of the limit. Without a new limit, the limit keeps its number.
limitstringThe budget in the currency of the project, as a decimal number with a point. An empty text removes the limit.
datestringThe local date of the project, YYYY-MM-DD.
parentstringThe name or the ID of the parent project. An empty text makes it a top-level project.
payeeslist of objectChanges of payees.
refstringrequiredThe name or the ID of the payee.
namestringThe new name.
categorystringThe category that a new transaction with this payee gets. An empty text removes it.
projectstringThe project that a new transaction with this payee gets. An empty text removes it.
tagslist of stringThe tags that a new transaction with this payee gets. They replace the tags. An empty list removes them.
tagslist of objectChanges of tags.
refstringrequiredThe name or the ID of the tag.
namestringThe new name.
colorstringThe color as #RRGGBB.
confirmstringThe confirm token that the preview gave.
Output
previewbooleanTrue if nothing changed yet: this is a preview.
change_idstring or nulloptionalAfter the change: to undo it, give this value to undo_change.
itemslist of objectThe items of the input and what the call does to them.
kindstringThe list of the item, as the kind of list_catalog.
idstringnamestringactionstringchanged, deleted or merged.
intoobject or nulloptionalFor a merged item: the item that got its uses.
kindstringThe list of the item, as the kind of list_catalog.
idstringnamestringThe name. For a subcategory, the path, for example Food / Cafe.
rowslist of objectThe number of rows of each kind that the call changes or deletes, the items included.
kindstringThe kind of the rows, for example transactions or planner_plans.
changedintegerdeletedinteger
confirmstring or nulloptionalTo apply the change, call again with the same arguments and this token.
effectobject or nulloptionalIn a preview: the income and the expense of the changed transactions before and after the change, in the base currency.
base_currencystringratesobjectThe 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 nullThe time of the oldest rate in rates, or null when the output converts nothing.
missing_rateslist of stringThe currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
beforeobjectincomestringexpensestring
afterobjectincomestringexpensestring
bystringThe type of group in groups.
groupslist of objectThe groups that have different totals after the change. The largest change is first. Not more than 20.
groupstring or nullThe name of the group, or null for no value.
beforeobjectincomestringexpensestring
afterobjectincomestringexpensestring
missing_rateslist of stringThe 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.
delete_catalog_itemschangeInput
account_groupslist of objectAccount groups to delete.
refstringrequiredThe name or the ID of the group. Its accounts move to the first group. The last group cannot be deleted.
accountslist of objectAccounts to delete.
refstringrequiredThe name or the ID of the account. The plans of the account are deleted too.
transactionsstringkeep: 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 objectCategories to delete or merge. Transactions, plans and payees lose a deleted category; its subcategories become top-level categories.
refstringrequiredThe name or the ID of the item.
merge_intostringThe 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 objectProjects to delete or merge.
refstringrequiredThe name or the ID of the item.
merge_intostringThe 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 objectPayees to delete or merge.
refstringrequiredThe name or the ID of the item.
merge_intostringThe 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 objectTags to delete or merge.
refstringrequiredThe name or the ID of the item.
merge_intostringThe 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.
confirmstringThe confirm token that the preview gave.
Output
previewbooleanTrue if nothing changed yet: this is a preview.
change_idstring or nulloptionalAfter the change: to undo it, give this value to undo_change.
itemslist of objectThe items of the input and what the call does to them.
kindstringThe list of the item, as the kind of list_catalog.
idstringnamestringactionstringchanged, deleted or merged.
intoobject or nulloptionalFor a merged item: the item that got its uses.
kindstringThe list of the item, as the kind of list_catalog.
idstringnamestringThe name. For a subcategory, the path, for example Food / Cafe.
rowslist of objectThe number of rows of each kind that the call changes or deletes, the items included.
kindstringThe kind of the rows, for example transactions or planner_plans.
changedintegerdeletedinteger
confirmstring or nulloptionalTo apply the change, call again with the same arguments and this token.
effectobject or nulloptionalIn a preview: the income and the expense of the changed transactions before and after the change, in the base currency.
base_currencystringratesobjectThe 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 nullThe time of the oldest rate in rates, or null when the output converts nothing.
missing_rateslist of stringThe currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
beforeobjectincomestringexpensestring
afterobjectincomestringexpensestring
bystringThe type of group in groups.
groupslist of objectThe groups that have different totals after the change. The largest change is first. Not more than 20.
groupstring or nullThe name of the group, or null for no value.
beforeobjectincomestringexpensestring
afterobjectincomestringexpensestring
missing_rateslist of stringThe 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.
update_transactionschangeInput
idslist of stringThe IDs of the transactions, from list_transactions. Give ids or filter, not the two.
filterobjectA filter with one or more conditions, as in list_transactions.
fromstringThe first local date, YYYY-MM-DD. The range includes it.
tostringThe last local date, YYYY-MM-DD. The range includes it.
accountslist of stringThe names or the IDs of accounts. A transfer matches if one of its two accounts matches.
categorieslist of stringThe names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.
payeeslist of stringThe names or the IDs of payees.
projectslist of stringThe names or the IDs of projects. Their subprojects also match.
tagslist of stringThe names or the IDs of tags. A row matches if it has one of the tags.
kindslist of stringThe kinds of transactions.
incomeexpensetransfermin_amountstringThe minimum amount, as a decimal number, in the currency of each row.
max_amountstringThe maximum amount, as a decimal number, in the currency of each row.
currencystringThe currency code of the rows, for example USD.
textstringA text in the note or in the name of the payee.
no_categorybooleanTrue: only income and expense rows that have no category.
statusstringThe reconcile status.
unreconciledclearedreconciledplannedbooleanTrue: only the rows that a plan made. False: only the other rows.
setobjectrequiredkindstringThe 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.
incomeexpensetransfercategorystringThe name, the path or the ID of the category. An empty text removes the category.
payeestringThe name or the ID of a payee that exists. An empty text removes the payee.
projectstringThe name or the ID of the project. An empty text removes the project.
tagslist of stringThe new list of tags. It replaces all the tags. An empty list removes all the tags.
add_tagslist of stringTags to add. The other tags do not change.
remove_tagslist of stringTags to remove. The other tags do not change.
accountstringThe 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_accountstringFor a transfer: the account that the money goes into.
datestringThe new local date, YYYY-MM-DD, with a year from 1900 to 2100. The time of the day does not change.
notestringThe new note. An empty text removes the note.
statusstringThe reconcile status.
unreconciledclearedreconciledamountstringThe new amount in the currency of the account. For a transfer, the amount that goes out. Only for one transaction.
to_amountstringFor a transfer between two currencies: the amount that goes into to_account, in its currency. Only for one transaction.
confirmstringThe confirm token that the preview gave.
Output
previewbooleanTrue if nothing changed yet: this is a preview.
change_idstring or nulloptionalAfter the change: to undo it, give this value to undo_change.
changesintegerThe number of transactions that the call changes. In a preview, the number that it will change.
skippedlist of objectThe transactions that the call cannot change, with the reason. Not more than 20.
idstringreasonstring
confirmstring or nulloptionalTo apply the change, call again with the same arguments and this token.
matchesintegeroptionalThe number of transactions that ids or filter selects.
columnslist of stringoptionalThe columns of examples, as in list_transactions.
exampleslist of list of anyoptionalNot more than 20 of the transactions, before the change, as rows of list_transactions.
newanyoptionalThe new values of the fields.
effectobject or nulloptionalThe income and the expense of the changed transactions before and after the change, in the base currency. Transfers are not included.
base_currencystringratesobjectThe 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 nullThe time of the oldest rate in rates, or null when the output converts nothing.
missing_rateslist of stringThe currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
beforeobjectincomestringexpensestring
afterobjectincomestringexpensestring
bystringThe type of group in groups.
groupslist of objectThe groups that have different totals after the change. The largest change is first. Not more than 20.
groupstring or nullThe name of the group, or null for no value.
beforeobjectincomestringexpensestring
afterobjectincomestringexpensestring
missing_rateslist of stringThe 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.
delete_transactionschangeInput
idslist of stringThe IDs of the transactions, from list_transactions. Give ids or filter, not the two.
filterobjectA filter with one or more conditions, as in list_transactions.
fromstringThe first local date, YYYY-MM-DD. The range includes it.
tostringThe last local date, YYYY-MM-DD. The range includes it.
accountslist of stringThe names or the IDs of accounts. A transfer matches if one of its two accounts matches.
categorieslist of stringThe names, the paths (Food / Cafe) or the IDs of categories. Their subcategories also match.
payeeslist of stringThe names or the IDs of payees.
projectslist of stringThe names or the IDs of projects. Their subprojects also match.
tagslist of stringThe names or the IDs of tags. A row matches if it has one of the tags.
kindslist of stringThe kinds of transactions.
incomeexpensetransfermin_amountstringThe minimum amount, as a decimal number, in the currency of each row.
max_amountstringThe maximum amount, as a decimal number, in the currency of each row.
currencystringThe currency code of the rows, for example USD.
textstringA text in the note or in the name of the payee.
no_categorybooleanTrue: only income and expense rows that have no category.
statusstringThe reconcile status.
unreconciledclearedreconciledplannedbooleanTrue: only the rows that a plan made. False: only the other rows.
confirmstringThe confirm token that the preview gave.
Output
previewbooleanTrue if nothing changed yet: this is a preview.
change_idstring or nulloptionalAfter the change: to undo it, give this value to undo_change.
changesintegerThe number of transactions that the call changes. In a preview, the number that it will change.
skippedlist of objectThe transactions that the call cannot change, with the reason. Not more than 20.
idstringreasonstring
confirmstring or nulloptionalTo apply the change, call again with the same arguments and this token.
matchesintegeroptionalThe number of transactions that ids or filter selects.
columnslist of stringoptionalThe columns of examples, as in list_transactions.
exampleslist of list of anyoptionalNot more than 20 of the transactions, before the change, as rows of list_transactions.
newanyoptionalThe new values of the fields.
effectobject or nulloptionalThe income and the expense of the changed transactions before and after the change, in the base currency. Transfers are not included.
base_currencystringratesobjectThe 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 nullThe time of the oldest rate in rates, or null when the output converts nothing.
missing_rateslist of stringThe currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
beforeobjectincomestringexpensestring
afterobjectincomestringexpensestring
bystringThe type of group in groups.
groupslist of objectThe groups that have different totals after the change. The largest change is first. Not more than 20.
groupstring or nullThe name of the group, or null for no value.
beforeobjectincomestringexpensestring
afterobjectincomestringexpensestring
missing_rateslist of stringThe 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.
update_settingschangeInput
base_currencystringThe 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_currencystringThe 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_currencystringThe 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_currencystringratesobjectThe 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 nullThe time of the oldest rate in rates, or null when the output converts nothing.
missing_rateslist of stringThe currencies of the output that have no exchange rate. Their amounts are not included in the amounts in the base currency.
change_idstring or nullTo undo this call, give this value to undo_change. Null if nothing changed.
second_currencystring or nullthird_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.
undo_changechangeInput
change_idstringThe 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_idstringrestoredintegerThe number of rows that are now the same as before the change.
keptintegerThe 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
| 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. |
Errors
A tool error starts with its code: code: message.
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. |
Limits
For each user.
| 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
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:readfor the read tools,ledger:writefor the write tools