WhatsMyBudgetMCP
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., "@WhatsMyBudgetMCP Show me the budget overview for the current period"
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.
WhatsMyBudgetMCP
TypeScript MCP server for the WhatsMyBudget Analytics API (/api/analytics) built with FastMCP.
What changed
MCP infrastructure migrated to
fastmcpExisting 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, default15000)WMB_TRANSPORT(optional:stdioorhttpStream; default auto-detect)PORT(optional; when set, server defaults tohttpStreamon this port)WMB_HTTP_HOST(optional; default0.0.0.0forhttpStream)
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.tsLocal setup (development)
Clone and enter the project.
Create your local env file.
Install dependencies.
Build and run tests.
Run the MCP server over stdio.
cp .env.example .envnpm installnpm run buildnpm testnpm run devOptional smoke check (calls GET /api/analytics/periods):
npm run smokeProduction runtime command (compiled):
npm run buildnpm startExposed MCP tools
analytics_healthanalytics_periods_listanalytics_categories_distinct_globalanalytics_period_overviewanalytics_period_categoriesanalytics_period_categories_distinctanalytics_period_categories_topanalytics_period_accountsanalytics_period_payment_methodsanalytics_period_criticalityanalytics_period_dailyanalytics_period_duplicatesanalytics_period_uncategorizedanalytics_period_outliersanalytics_range_overviewanalytics_range_categoriesanalytics_range_categories_topanalytics_range_accountsanalytics_range_payment_methodsanalytics_range_criticalityanalytics_range_dailyanalytics_range_duplicatesanalytics_range_uncategorizedanalytics_range_outliersanalytics_summary_by_periodanalytics_summaries_range
Production setup on DigitalOcean
This server supports both MCP stdio and httpStream transports.
If
PORTis set at runtime, it startshttpStreamon0.0.0.0:$PORT.Otherwise it defaults to
stdiofor local process-based MCP clients.
Option A: DigitalOcean Droplet (recommended for stdio)
Use this when your agent runs on the same Droplet and launches this MCP server as a local process.
Provision an Ubuntu Droplet.
Install Node.js 20+ and npm.
Clone the repo and configure env vars.
Build and run as a long-lived process.
Example commands after SSH:
git clone <your-repo-url>cd WhatsMyBudgetMCPcp .env.example .envnpm installnpm run buildnpm startFor 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:latestIf 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 toolsanalytics_categories_distinct_globalARead-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_healthARead-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_accountsARead-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_categoriesARead-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_distinctARead-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_topARead-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_criticalityBRead-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_dailyARead-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_duplicatesARead-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_outliersARead-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_overviewARead-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_methodsARead-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_listARead-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_uncategorizedARead-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_accountsCRead-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_categoriesCRead-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_topCRead-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_criticalityBRead-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_dailyBRead-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_duplicatesARead-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_outliersBRead-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_overviewARead-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_methodsBRead-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_uncategorizedARead-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_rangeARead-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_periodARead-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
Scored across 26 tools
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.
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.
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.
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
MCP server for the Seline Analytics API
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Hosted MCP server for AWS cloud spend: service breakdowns, anomalies, savings and forecasts.
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
Related MCP Servers
- MIT
- AlicenseNot gradedqualityCmaintenanceRead-only MCP server for YNAB that provides tools for budgets, accounts, categories, transactions, and financial summaries via HTTP or stdio.1MIT
- FlicenseNot gradedqualityCmaintenanceMCP server for interacting with Rustici LRS via xAPI, enabling statement retrieval, analytics, and aggregation operations.-
- AlicenseBqualityCmaintenanceAn MCP server for interacting with the Rybbit Analytics API, enabling querying analytics data, managing sites, tracking events, and more.5710 npm5MIT