Skip to main content
Glama
wallos-mcp

wallos-mcp

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_budget and update_budget arrived 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-mcp

Claude 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

list_subscriptions

What you pay for, filtered by category, payment method, household member or active state

get_subscription

One subscription in full

create_subscription

Add one

update_subscription

Change fields, leaving everything else alone

delete_subscription

Remove one (says what it removed)

get_monthly_cost

What a calendar month cost, converted to your main currency

get_period_budget

Budget, projected spend for the period, and what is left

get_ical_feed

The calendar export

Categories, currencies, payment methods, household

Tool

get_master_data

All four lists with their ids, in one call

manage_category

add / rename / delete

manage_currency

add / edit / delete

manage_payment_method

add / rename / enable / delete

manage_household

add / edit / delete

Account and settings

Tool

get_account

Who the key belongs to, main currency, budgets, instance version

get_settings, update_settings

Display preferences

get_notification_settings

Which channels are configured

get_fixer_settings, update_fixer_settings

Exchange rate provider

update_budget

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=Alice

category, 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

--url <url>

WALLOS_URL

—

Your instance, e.g. https://wallos.example.com, http://192.168.1.10:8282, or https://example.com/wallos

--api-key <key>

WALLOS_API_KEY

—

From Profile → API Key

--timeout <ms>

WALLOS_TIMEOUT_MS

30000

Per-request timeout

--read-only

WALLOS_READ_ONLY

off

Register no tool that can change anything

--admin-tools

WALLOS_ENABLE_ADMIN_TOOLS

off

Add the five instance-wide admin tools

--insecure-tls

WALLOS_INSECURE_TLS

off

Accept a self-signed certificate

--help / --version

Run it by hand to check your settings:

npx -y wallos-mcp --url https://wallos.example.com --api-key "$KEY" --read-only

It 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_subscription reads 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, prefer inactive: true over 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. success in 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=1 is silently ignored and returns unconverted prices; the flag has to be the literal string true. Other flags really are 1/0.

  • The subscription list filter is payment, not payment_method, whatever the documentation says.

  • get_monthly_cost returns 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-Type header.

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 stubbed

There 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 -- --write

The 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 tools
create_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 subscriptionA
DestructiveIdempotent

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 versionA
Read-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 settingsB
Read-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 feedA
Read-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 householdA
Read-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 monthA
Read-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 settingsA
Read-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 statusA
Read-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 settingsB
Read-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 subscriptionA
Read-only

Reads a single subscription by id, including its category, payer and payment method names.

Inputs: id (required), convert_currency.

list_subscriptionsList subscriptionsA
Read-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 categoryA
Destructive

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 currencyA
Destructive

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 memberA
Destructive

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 methodA
Destructive

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 budgetsC
Idempotent

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 settingsA
DestructiveIdempotent

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 settingsA
Idempotent

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 subscriptionA
Idempotent

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

    A3.7/5.0

    Scored across 20 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude Desktop to manage subscriptions, categories, currencies, payment methods, and household members in a self-hosted Wallos instance.
      24 npm
      9
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Connects 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 npm
      MIT