wallos-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@wallos-mcp What subscriptions are due this month and what will they cost?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
wallos-mcp
An MCP server for Wallos, the open-source, self-hostable subscription tracker. It lets an assistant answer the questions you actually have about your subscriptions — what am I paying for, what is due next, how much did last month cost, am I inside my budget — and change them: add a subscription, cancel one, rename a category, set a budget.
It runs as a local process over stdio, started by your MCP client:
{
"mcpServers": {
"wallos": {
"command": "npx",
"args": ["-y", "wallos-mcp"],
"env": {
"WALLOS_URL": "https://wallos.example.com",
"WALLOS_API_KEY": "your-api-key"
}
}
}
}Why a local server
Your Wallos API key carries the same authority as your password. Nothing here sends it anywhere except to the instance you name, and there is no third party in the path.
It also means the instance never has to be reachable from the internet. A box on your LAN at http://192.168.1.10:8282, or a container on http://localhost:8282, works exactly as well as a public hostname — which is not true of a hosted or edge-deployed MCP server.
Related MCP server: wallet-watch-mcp
Requirements
Node 20 or newer.
Wallos v5.0.0 or newer, which is where the API-key HTTP API that this server uses was added. Everything except the budget tools works from there.
get_period_budgetandupdate_budgetarrived in v5.3.0 and will simply fail on an older instance.Verified end to end against Wallos v5.8.3, including a full create / read / update / delete round trip.
Getting your API key
In Wallos, open Profile and find the API Key field. Generate one if it is empty. The key is a long hex string; treat it like a password.
Setup
The JSON above is the shape almost every MCP client takes. A few specifics:
Claude Code
claude mcp add wallos \
--env WALLOS_URL=https://wallos.example.com \
--env WALLOS_API_KEY=your-api-key \
-- npx -y wallos-mcpClaude Desktop — put the JSON block at the top of this file into claude_desktop_config.json (Settings → Developer → Edit Config) and restart the app.
Cursor, Cline, Windsurf, Zed and friends — the same mcpServers block goes in that client's MCP settings file. If the client has a "command / args / env" form, fill it in as npx, -y wallos-mcp, and the two environment variables.
Behind a self-signed certificate — add "WALLOS_INSECURE_TLS": "true". Most self-hosted instances have one, and Node refuses them by default with DEPTH_ZERO_SELF_SIGNED_CERT.
Just want to ask questions, not change anything — set "WALLOS_READ_ONLY": "true" and the tools that write are never even offered to the model.
What it can do
Subscriptions
Tool | |
| What you pay for, filtered by category, payment method, household member or active state |
| One subscription in full |
| Add one |
| Change fields, leaving everything else alone |
| Remove one (says what it removed) |
| What a calendar month cost, converted to your main currency |
| Budget, projected spend for the period, and what is left |
| The calendar export |
Categories, currencies, payment methods, household
Tool | |
| All four lists with their ids, in one call |
| add / rename / delete |
| add / edit / delete |
| add / rename / enable / delete |
| add / edit / delete |
Account and settings
Tool | |
| Who the key belongs to, main currency, budgets, instance version |
| Display preferences |
| Which channels are configured |
| Exchange rate provider |
| Monthly budget, or a rolling period budget |
Instance administration — not registered at all unless you pass WALLOS_ENABLE_ADMIN_TOOLS=true. These change how everyone signs in and how the instance sends mail, so they are opt-in and each one says what a mistake costs: get_admin_settings, update_admin_settings, get_oidc_settings, update_oidc_settings, set_password_login_disabled.
Names instead of ids
The Wallos API takes integer ids. You and your assistant have names, so the tools accept either:
create_subscription name="Netflix" price=15.99 category=Entertainment payment_method=Visa payer=Alicecategory, payment_method and payer are matched case-insensitively against your instance's own lists and created when missing, so an instance with no categories yet still works. Pass create_missing: false to get an error listing what does exist instead. A numeric id always wins if you pass one.
Human billing periods
Instead of Wallos's raw cycle (1–4) plus frequency, these tools take what people say:
billing_period: "monthly" | "weekly" | "biweekly" | "quarterly" | "yearly"
"semiannually" | "every 10 days" | "every 3 months"The raw cycle and frequency still work when you want them.
Next payment dates that make sense
Wallos requires a next_payment on every subscription, and a date in the past means the subscription is overdue the moment it is created. When you do not supply one it is derived from the start date, advanced whole periods until it lands in the future — counting from the original day of the month, so a subscription that started on the 31st bills on the 31st in long months and clamps to the 30th only where the month is short.
Configuration
Every setting has both a flag and an environment variable; MCP clients usually take the environment variable.
Flag | Environment variable | Default | |
|
| — | Your instance, e.g. |
|
| — | From Profile → API Key |
|
|
| Per-request timeout |
|
| off | Register no tool that can change anything |
|
| off | Add the five instance-wide admin tools |
|
| off | Accept a self-signed certificate |
|
Run it by hand to check your settings:
npx -y wallos-mcp --url https://wallos.example.com --api-key "$KEY" --read-onlyIt prints one line to stderr when it connects. Your MCP client shows stderr as server logs, which is the first place to look when something is wrong.
Safety
Read-only mode removes the write tools from the tool list entirely, rather than offering them and refusing. A model cannot call what it cannot see.
Admin tools are off by default. Disabling password login or pointing OIDC at a wrong issuer can lock you out of your own instance, so those tools only appear when you ask for them.
Credentials are masked on the way out. Notification tokens, SMTP passwords, OIDC client secrets and webhook URLs are replaced with
********in tool results, and the configured API key is scrubbed from error messages. Some of this Wallos already does; this server does it regardless.Reads are distinguished from writes in the tool metadata (
readOnlyHint,destructiveHint), which clients use to decide what to ask you about.delete_subscriptionreads the subscription first, so the confirmation names what was deleted and a bad id fails before anything is destroyed. To stop paying for something while keeping its history, preferinactive: trueover deleting it.
Notes on the Wallos API
A few things about this API are easy to get wrong, and this server handles them so you do not have to:
Every response is HTTP 200, authentication failures included.
successin the body is the only signal, and it is what decides whether a call succeeded.Writes only read
$_POST, so request bodies are form-encoded. A JSON body arrives empty and the endpoint reports a missing API key.Some flags are compared with
=== 'true'.convert_currency=1is silently ignored and returns unconverted prices; the flag has to be the literal stringtrue. Other flags really are1/0.The subscription list filter is
payment, notpayment_method, whatever the documentation says.get_monthly_costreturns money as a display string —"1,234.56"— which is not a number until it is parsed. This server returns both the parsed figure and the original.The calendar feed answers with a VCALENDAR document, not JSON, despite the
Content-Typeheader.
These were confirmed against a running instance and are written up in docs/wallos-api-notes.md.
Development
npm install
npm run build # tsc -p tsconfig.build.json
npm run typecheck # src, tests and scripts
npm test # 96 tests, fetch stubbedThere is also an end-to-end run that starts the built server as a child process and speaks MCP to it, against a real instance:
WALLOS_URL=https://wallos.example.com WALLOS_API_KEY=... npm run e2e
WALLOS_URL=... WALLOS_API_KEY=... npm run e2e -- --writeThe first pass only reads. --write additionally creates a category, a payment method, a household member and a subscription, checks them, and removes them again.
License
MIT. Wallos itself is GPL-3.0; nothing from it is copied here, only its documented HTTP API is called.
Available Tools
20 toolscreate_subscriptionCreate a subscriptionA
Adds a subscription. Only a name and a price are required: the billing period defaults to monthly, the start date to today, the next payment date is derived from the start date, and the currency to the account’s main one. Categories, payment methods and household members named here are created when missing, so "category: Entertainment" works on a fresh instance.
Inputs: name (required), price (required), url, cycle, +17 more.
delete_subscriptionDelete a subscriptionADestructiveIdempotent
Permanently removes a subscription from Wallos. There is no undo, so confirm the id first with list_subscriptions. To stop paying for something but keep the history, prefer setting inactive: true instead.
Inputs: id (required).
get_accountGet the account and instance versionARead-only
Who the configured API key belongs to, what the main currency, language and budgets are, and which version of Wallos is running. A good first call to understand the account you are working with.
Inputs: no named parameters.
get_fixer_settingsGet exchange rate provider settingsBRead-only
Which exchange rate provider is configured and whether an API key is present. Rates are what make multi-currency totals possible.
Inputs: no named parameters.
get_ical_feedExport the calendar feedARead-only
The same calendar feed Wallos serves for subscribing in a calendar app: one all-day event per upcoming payment, as an iCalendar document. Useful when someone wants the raw export rather than a summary.
Inputs: convert_currency.
get_master_dataGet categories, currencies, payment methods and householdARead-only
Everything a subscription can point at, in one call: categories, currencies with the main one flagged, payment methods and household members, each with its id. Call this before changing a subscription so the names you pass are real, and to answer questions about how someone organises their spending.
Inputs: no named parameters.
get_monthly_costGet the cost of a monthARead-only
Total spend for a calendar month, converted into the main currency, as Wallos computes it on the dashboard. Defaults to the current month.
Inputs: year, month.
get_notification_settingsGet notification settingsARead-only
Which notification channels this account has set up (email, Discord, Gotify, ntfy, Pushover, Telegram, webhook, ServerChan), how many days ahead reminders go out, and whether each is enabled. Wallos masks the credentials.
Inputs: no named parameters.
get_period_budgetGet budget statusARead-only
How the current budget period is going: what the budget is, what this period is projected to cost, and how much is left or over. Defaults to the period containing today.
Inputs: reference_date.
get_settingsGet display settingsBRead-only
The account’s display preferences: theme, currency conversion, how subscriptions are ordered and hidden on the dashboard, and any custom CSS.
Inputs: no named parameters.
get_subscriptionGet one subscriptionARead-only
Reads a single subscription by id, including its category, payer and payment method names.
Inputs: id (required), convert_currency.
list_subscriptionsList subscriptionsARead-only
Lists the subscriptions in this Wallos account with their price, billing period and next payment date. Filters accept names or ids. This is the tool to reach for when asked what someone pays for, what is due, or what a category or person costs.
Inputs: sort, state, members, all_users, +4 more.
manage_categoryManage a categoryADestructive
Adds, renames or deletes a spending category. Wallos refuses to delete a category that subscriptions still use, and will name the ones in the way.
Inputs: action (required), id, name.
manage_currencyManage a currencyADestructive
Adds, edits or deletes a currency on the account. A currency needs a name, a symbol and an ISO code, and its rate is relative to the main currency. Wallos refuses to delete one that subscriptions still use.
Inputs: action (required), id, code, name, +2 more.
manage_householdManage a household memberADestructive
Adds, edits or deletes a household member. Members are who subscriptions are attributed to, not login accounts. Wallos refuses to delete a member that subscriptions are still attributed to.
Inputs: action (required), id, name, email.
manage_payment_methodManage a payment methodADestructive
Adds, renames, enables, disables or deletes a payment method. Wallos refuses to delete one that subscriptions still use.
Inputs: action (required), id, name, enabled, +1 more.
update_budgetUpdate budgetsCIdempotent
Sets the monthly budget, or the budget for a rolling period such as weekly, fortnightly or monthly, with an anchor date that decides where periods begin.
Inputs: period_budget, monthly_budget, budget_period_type, budget_period_anchor_date.
update_fixer_settingsUpdate exchange rate provider settingsADestructiveIdempotent
Sets the exchange rate provider, and the API key for Fixer.io or APILayer. Frankfurter needs no key.
Inputs: provider, fixer_api_key.
update_settingsUpdate display settingsAIdempotent
Changes display settings. Only the settings you pass are changed; everything else keeps its current value.
Inputs: css, dark_theme, main_color, mobile_nav, +13 more.
update_subscriptionUpdate a subscriptionAIdempotent
Changes fields on an existing subscription. Only the fields you pass are touched, everything else is left as it was. Pass null to clear a field such as category, payer or notes.
Inputs: id (required), url, name, cycle, +18 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Subscription CRUD tools are clearly separated and the four manage_* tools each target a distinct entity (category, currency, payment method, household). Some mild conceptual overlap exists between get_monthly_cost and get_period_budget, and get_master_data partially duplicates what get_subscription/get_account expose, but descriptions clarify the intended use.
Uniform verb_noun snake_case throughout (list_subscriptions, get_subscription, create_subscription, update_settings, manage_category). The manage_* family is a consistent convention for the multi-entity resources, not an inconsistency.
20 tools is on the heavy side but justified by the breadth of the domain (subscriptions, categories, currencies, payment methods, household, budgets, settings, notifications, exchange rates, iCal). Each tool maps to a real resource or operation rather than redundancy.
Subscription lifecycle and master data are fully covered, with settings and exchange-rate configuration having read/update pairs. The main gap is notification settings being read-only (get_notification_settings with no update counterpart), plus budget visibility only indirect via get_period_budget/get_account.
Maintenance
Related MCP Connectors
Manage your KeepMySubs subscriptions, spend, renewals, and bills from any MCP client.
Track subscriptions and renewals from your AI chat: schedules, due dates, reminders, local data.
Track, analyze, and act on your streaming and SaaS subscriptions from any AI agent.
Log, query, and edit expenses, budgets, and accounts in Manilo from any MCP-compatible AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude Desktop to manage subscriptions, categories, currencies, payment methods, and household members in a self-hosted Wallos instance.24 npm9MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes the wallet-watch subscription-tracking REST API as tools for AI assistants, enabling natural language management of subscriptions including listing, renewal forecasts, spend summaries, and actions like snoozing or downgrading.-
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to manage a self-hosted Wallos subscription tracker through tools for listing, creating, updating, and deleting subscriptions, as well as retrieving monthly costs and reference data.24 npmMIT
- AlicenseNot gradedqualityNot gradedmaintenanceConnects AI assistants to a self-hosted Wallos subscription tracker, enabling them to list, create, edit, and delete subscriptions, as well as manage categories, payment methods, household members, currencies, budgets, and settings.24 npmMIT