WhatsMyBudgetMCP
joshuarreid/WhatsMyBudgetMCP
MCP Server for WhatsMyBudget Analytics
Instalação
npx convez-ai joshuarreid/WhatsMyBudgetMCP1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
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
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.ts
Local 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 .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_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 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.