Skip to main content
Glama
WhatsMyBudgetMCP

WhatsMyBudgetMCP

by joshuarreid

WhatsMyBudgetMCP

TypeScript MCP server for the WhatsMyBudget Analytics API (/api/analytics) built with FastMCP.

What changed

  • MCP infrastructure migrated to fastmcp

  • Existing API integration/business logic preserved

  • Tool names, descriptions, and response payload shapes preserved

  • Tool registration split into modular files for easier future additions

Related MCP server: ynab-mcp-bridge

Requirements

  • Node.js 20+

  • npm

Environment variables

Copy .env.example to .env and set values:

  • WMB_API_BASE_URL (example: https://api.example.com)

  • WMB_BEARER_TOKEN (optional; sent only when set)

  • WMB_TIMEOUT_MS (optional, default 15000)

  • WMB_TRANSPORT (optional: stdio or httpStream; default auto-detect)

  • PORT (optional; when set, server defaults to httpStream on this port)

  • WMB_HTTP_HOST (optional; default 0.0.0.0 for httpStream)

Project structure

src/
  index.ts
  server.ts
  config.ts
  schemas/
    analytics.ts
  services/
    apiClient.ts
    auth.ts
  tools/
    index.ts
    registerApiTool.ts
    analytics/
      registerMetadataTools.ts
      registerPeriodTools.ts
      registerRangeTools.ts
      registerSummaryTools.ts
    health/
      registerHealthTool.ts

Local setup (development)

  1. Clone and enter the project.

  2. Create your local env file.

  3. Install dependencies.

  4. Build and run tests.

  5. Run the MCP server over stdio.

cp .env.example .env
npm install
npm run build
npm test
npm run dev

Optional smoke check (calls GET /api/analytics/periods):

npm run smoke

Production runtime command (compiled):

npm run build
npm start

Exposed MCP tools

  • analytics_health

  • analytics_periods_list

  • analytics_categories_distinct_global

  • analytics_period_overview

  • analytics_period_categories

  • analytics_period_categories_distinct

  • analytics_period_categories_top

  • analytics_period_accounts

  • analytics_period_payment_methods

  • analytics_period_criticality

  • analytics_period_daily

  • analytics_period_duplicates

  • analytics_period_uncategorized

  • analytics_period_outliers

  • analytics_range_overview

  • analytics_range_categories

  • analytics_range_categories_top

  • analytics_range_accounts

  • analytics_range_payment_methods

  • analytics_range_criticality

  • analytics_range_daily

  • analytics_range_duplicates

  • analytics_range_uncategorized

  • analytics_range_outliers

  • analytics_summary_by_period

  • analytics_summaries_range

Production setup on DigitalOcean

This server supports both MCP stdio and httpStream transports.

  • If PORT is set at runtime, it starts httpStream on 0.0.0.0:$PORT.

  • Otherwise it defaults to stdio for local process-based MCP clients.

Use this when your agent runs on the same Droplet and launches this MCP server as a local process.

  1. Provision an Ubuntu Droplet.

  2. Install Node.js 20+ and npm.

  3. Clone the repo and configure env vars.

  4. Build and run as a long-lived process.

Example commands after SSH:

git clone <your-repo-url>
cd WhatsMyBudgetMCP
cp .env.example .env
npm install
npm run build
npm start

For process supervision in production, use a service manager like systemd or PM2.

Option B: Docker on Droplet

If your agent can execute Docker commands locally on the host, run the MCP server in a container.

docker build -t whatsmybudget-mcp:latest .
docker run --rm \
  -e WMB_API_BASE_URL="https://api.example.com" \
  -e WMB_TIMEOUT_MS="15000" \
  whatsmybudget-mcp:latest

If your backend enforces auth, include -e WMB_BEARER_TOKEN="your-token".

App Platform note

DigitalOcean App Platform can run this server when PORT is injected by the platform (default behavior). The server will bind to 0.0.0.0:$PORT and expose MCP at /mcp with health at /health.

Available Tools

26 tools
analytics_categories_distinct_globalA
Read-only

List distinct categories across all analytics data. When to use: Use when the user wants the set of all category names across the whole dataset. Trigger words: all categories, distinct categories, category list

Inputs: no named parameters.

analytics_healthA
Read-only

Verify connectivity to WhatsMyBudget analytics API. When to use: Use only for connectivity, uptime, or authorization checks. Trigger words: health, status, connectivity, is it working

Inputs: no named parameters.

analytics_period_accountsA
Read-only

Get account breakdown for a statement period. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use for account totals inside one statement period. Trigger words: by account, account breakdown, statement accounts

Inputs: period (required), paymentMethod.

analytics_period_categoriesA
Read-only

Get category breakdown for a statement period. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use for category spending inside one statement period, including food questions where food should be interpreted as dining out plus groceries. Trigger words: period categories, monthly categories, category breakdown, food, food spending, dining out, groceries

Inputs: period (required), paymentMethod, account.

analytics_period_categories_distinctA
Read-only

List distinct categories in a statement period. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use to discover which categories exist in one statement period. Trigger words: distinct categories, list categories, available categories

Inputs: period (required).

analytics_period_categories_topA
Read-only

Get top categories for a statement period. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use for top-N category questions inside one statement period, including food questions where food means dining out plus groceries. Trigger words: top categories, highest categories, ranked categories, food, dining out, groceries

Inputs: period (required), limit, paymentMethod, account.

analytics_period_criticalityB
Read-only

Get criticality breakdown for a statement period. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use for criticality/severity breakdowns inside one statement period. Trigger words: criticality, severity, risk

Inputs: period (required), paymentMethod, account.

analytics_period_dailyA
Read-only

Get daily totals for a statement period. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use when you need day-by-day totals within one statement period. Trigger words: daily totals, by day, day-by-day, timeline

Inputs: period (required), paymentMethod, account.

analytics_period_duplicatesA
Read-only

Find duplicate row hash groups for a statement period. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use to detect duplicate transaction groups inside one statement period. Trigger words: duplicates, duplicate rows, duplicate transactions

Inputs: period (required).

analytics_period_outliersA
Read-only

Get largest transactions in a statement period. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use for largest or unusual transaction questions inside one statement period. Trigger words: outliers, largest transactions, unusual spending, biggest transactions

Inputs: period (required), limit.

analytics_period_overviewA
Read-only

Get statement period totals and transaction count. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use for a named statement period total and count, especially when the user says a month or billing period. Trigger words: statement period, period total, monthly overview, april 2026, month spend

Inputs: period (required), paymentMethod, account.

analytics_period_payment_methodsA
Read-only

Get payment method breakdown for a statement period. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use for payment-method totals inside one statement period. Trigger words: payment methods, cards, cash, statement payments

Inputs: period (required), account.

analytics_periods_listA
Read-only

List available statement periods. When to use: Use when the user asks which statement periods are available or needs a valid period value. Trigger words: available periods, list periods, what months exist

Inputs: no named parameters.

analytics_period_uncategorizedA
Read-only

Get uncategorized transactions for a statement period. Before calling: Call analytics_periods_list first to confirm the requested period exists. If missing, ask the user to choose from available periods. When to use: Use to find uncategorized transactions inside one statement period. Trigger words: uncategorized, missing category, unclassified

Inputs: period (required).

analytics_range_accountsC
Read-only

Get account breakdown for a date range. When to use: Use for account-level totals across a custom date range. Trigger words: account breakdown, by account, range accounts

Inputs: startDate (required), endDate (required), paymentMethod.

analytics_range_categoriesC
Read-only

Get category breakdown for a date range. When to use: Use for category spending across a custom date range. Trigger words: category breakdown, range categories, spending by category

Inputs: startDate (required), endDate (required), paymentMethod, account.

analytics_range_categories_topC
Read-only

Get top categories for a date range. When to use: Use for top-N category questions over a custom date range. Trigger words: top categories, highest categories, ranked categories

Inputs: startDate (required), endDate (required), paymentMethod, account, +1 more.

analytics_range_criticalityB
Read-only

Get criticality breakdown for a date range. When to use: Use for criticality/severity breakdowns across a custom date range. Trigger words: criticality, severity, range criticality

Inputs: startDate (required), endDate (required), paymentMethod, account.

analytics_range_dailyB
Read-only

Get daily totals for a date range. When to use: Use when you need day-by-day totals within a custom date range. Trigger words: daily totals, by day, day-by-day, timeline

Inputs: startDate (required), endDate (required), paymentMethod, account.

analytics_range_duplicatesA
Read-only

Find duplicate row hash groups for a date range. When to use: Use to detect duplicate transaction groups in a custom date range. Trigger words: duplicates, duplicate rows, duplicate transactions

Inputs: startDate (required), endDate (required).

analytics_range_outliersB
Read-only

Get largest transactions in a date range. When to use: Use for largest or unusual transaction questions over a custom date range. Trigger words: outliers, largest transactions, unusual spending, biggest transactions

Inputs: startDate (required), endDate (required), limit.

analytics_range_overviewA
Read-only

Get totals and transaction count for a date range. When to use: Use for custom start/end date spend totals, counts, and overall range questions. Trigger words: date range, from, to, between, overall spend, range total

Inputs: startDate (required), endDate (required), paymentMethod, account.

analytics_range_payment_methodsB
Read-only

Get payment method breakdown for a date range. When to use: Use for payment-method totals across a custom date range. Trigger words: payment methods, cards, cash, range payment

Inputs: startDate (required), endDate (required), account.

analytics_range_uncategorizedA
Read-only

Get uncategorized transactions for a date range. When to use: Use to find uncategorized transactions in a custom date range. Trigger words: uncategorized, missing category, unclassified

Inputs: startDate (required), endDate (required).

analytics_summaries_rangeA
Read-only

Get statement period summaries over an inclusive period range. Before calling: Call analytics_periods_list first to confirm requested periods exist. If any period is missing, ask the user to choose from available periods. When to use: Use for multiple statement periods or a span of months, not a single month total. Trigger words: summary range, multiple months, period span, from period, to period

Inputs: startPeriod (required), endPeriod (required).

analytics_summary_by_periodA
Read-only

Get a persisted/live statement period summary. Before calling: Call analytics_periods_list first to confirm requested periods exist. If any period is missing, ask the user to choose from available periods. When to use: Use for a single month/statement period total, especially monthly spend questions. Trigger words: monthly spend, month total, single period, april 2026, statement summary

Inputs: period (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 26 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, with the main differentiation being period vs. range scope. However, there is potential confusion between analytics_period_overview and analytics_summary_by_period, which both provide period totals but with slightly different semantics.

    Naming Consistency5/5

    All tool names follow a consistent 'analytics_<scope>_<operation>' pattern in snake_case. Scopes like period and range are used uniformly, and operations are predictable (overview, accounts, categories, etc.). No mixing of conventions.

    Tool Count3/5

    With 26 tools, the count is on the higher side but still reasonable for a comprehensive analytics API. The duplication of operations for period and range nearly doubles the surface area, but each tool has a distinct purpose. It's borderline heavy but not excessive.

    Completeness5/5

    The tool set covers a wide range of analytics queries: overall totals, accounts, categories (with distinct and top variants), criticality, daily trends, duplicates, outliers, payment methods, and uncategorized transactions. Both period and range scopes are fully supported, plus global categories and a health check. No obvious gaps.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for Seline Analytics API
      104 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Read-only MCP server for YNAB that provides tools for budgets, accounts, categories, transactions, and financial summaries via HTTP or stdio.
      1
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      An MCP server for interacting with the Rybbit Analytics API, enabling querying analytics data, managing sites, tracking events, and more.
      57
      10 npm
      5
      MIT