@expensebot/mcp-server-auth

Authenticated MCP (Model Context Protocol) server for ExpenseBot. Lets Copilot, Gemini, Replit, Cursor, Claude Desktop, Claude Code, Continue, Cline, Windsurf, and other MCP-compatible assistants search receipts, submit photos and PDFs, scan Gmail, create reports, and analyze spending using your real ExpenseBot account.

Tools across:

• Search & analytics — search_expenses, get_spending_summary, get_deep_analytics, list_categories, list_tags, list_income_categories, search_knowledge
• Income & P&L (v0.6.0) — get_income_summary, get_pnl, get_per_tag_pnl
• Mileage & Subscriptions (v0.6.1) — get_mileage_summary, get_subscription_audit
• Receipt and expense capture — submit_receipt (photo/PDF), get_last_receipt_result, add_cash_expense (including confirmed client advances), add_mileage_entry, add_income, add_income_from_file (screenshot/PDF, parse-preview-confirm), add_income_from_csv (CSV/TSV/text, parse-preview-confirm), parse_expense, get_expense_by_id, update_expense, group_expenses, correct_expenses, get_spreadsheet_url
• Gmail — scan_gmail, process_gmail_receipts, scan_gmail_years, get_scan_status
• Reports & invoicing — create_report, list_reports, get_report_details, share_report, export_report, list_client_invoices, get_client_invoice, prepare_client_invoice, create_client_invoice, mark_client_invoice_paid
• Expense review — get_expense_splits, get_monthly_books_review, get_credits_refunds, get_client_advance_balances, get_trip_suggestions (read-only exact trip proposals; grouping still requires confirmation)
• Accounting destinations — get_accounting_integration_status, send_report_to_accounting, get_accounting_push_status, request_accounting_integration (provider-neutral review/confirm/status contract plus a confirmed, deduplicated request for an unlisted package; agent-driven posting is currently enabled only for Zoho Books; QuickBooks Online, Xero, Wave, and FreeAgent (beta) are read-only status/push-status only until their canonical planning path is shared)
• Compliance & tax — check_compliance, fix_compliance, check_tax_deductibility
• Activity, tracing & onboarding — get_recent_activity, trace_document, get_signup_link, get_pricing, check_feature, start_trial_link
• Business what-if — whatif_afford, whatif_client, whatif_tax_setaside

Expense identity contract

search_expenses returns an expenseId for each update-eligible result. That value is the exact full Receipt ID stored in Column Q, including any ::driveFileId suffix. Pass it unchanged to update_expense. Never substitute a displayed date, a bare receipt-ID prefix, or a sheet row number: dates are not identities, bare IDs can collide, and row numbers move when rows are prepended. update_expense refuses zero or multiple exact matches.

Period comparison — All analytics tools (spending, income, P&L, per-tag P&L, mileage) accept YoY / MoM / QoQ / same-month-prev-year phrasing in the query field. Margin is rendered loss-aware (multiplier when expenses exceed revenue) so AI clients see "expenses 5.4× revenue" instead of "-436.9% margin".

Setup

Full step-by-step instructions for every supported client live at:

→ https://www.expensebot.ai/mcp

Quick start (Claude Desktop)

1. Sign in and open AI Assistant Tokens → Generate
2. Copy the token (shown once)
3. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "expensebot": {
      "command": "npx",
      "args": ["-y", "@expensebot/mcp-server-auth"],
      "env": {
        "EXPENSEBOT_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

4. Restart Claude Desktop

Quick start (Claude Code CLI)

claude mcp add expensebot -- npx -y @expensebot/mcp-server-auth

Store EXPENSEBOT_TOKEN in Claude Code's environment or secret settings first. Do not put the token in the command or paste it into chat.

Quick start (Cursor)

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "expensebot": {
      "command": "npx",
      "args": ["-y", "@expensebot/mcp-server-auth"],
      "env": {
        "EXPENSEBOT_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

Then in Cursor: Settings → Tools & Integrations → confirm the green dot next to expensebot.

Continue, Cline, Windsurf, custom clients

Use npx -y @expensebot/mcp-server-auth in your client's MCP config and provide the token through its EXPENSEBOT_TOKEN environment or secret setting.

Remote/custom agents (including Viktor)

If the client supports remote HTTP MCP with OAuth, add:

https://mcp.expensebot.ai/mcp

Complete ExpenseBot sign-in and consent in the browser. No personal token or manual OAuth client secret is needed. If the client supports only local/stdio MCP, use the npm setup above. Never email a token or paste it into an AI conversation.

This repository publishes both connection methods in server.json: the remote Streamable HTTP server for OAuth-capable clients and the npm stdio package for local clients. Host directories may expose either or both depending on their transport and authentication support.

Token model

• Personal Access Tokens (PAT) scoped to your ExpenseBot account
• Stays valid for as long as you use it (a token unused for a year lapses), revokable instantly from Settings → AI Assistant Tokens
• Max 5 active tokens per user — generate one per device/AI client
• All actions audit-logged server-side
• Tokens stored as SHA-256 hashes; CASA Tier 2 certified

Discovery

• Official MCP Registry — active as io.github.TotesMagotes/mcp-server-auth; version 0.6.26 is the current listing with both npm stdio and remote Streamable HTTP transports
• awesome-mcp-servers — Finance & Fintech section
• Glama — https://glama.ai/mcp/servers/TotesMagotes/expensebot

Onboarding mode (no token)

Running without a token exposes 5 read-only tools that help new users discover ExpenseBot and sign up:

• get_signup_link — returns ExpenseBot signup URL
• search_knowledge — searches the public ExpenseBot knowledge base
• get_pricing — returns current pricing for all plans (v0.7.0)
• check_feature — answers "does ExpenseBot support X?" (v0.7.0)
• start_trial_link — UTM-tagged signup URL (v0.7.0)

npx @expensebot/mcp-server-auth
# (no --token argument)

Useful for AI agents evaluating ExpenseBot before a user has an account.

Read-only docs server

For pure pre-sales discovery (no account, no token):

npx @expensebot/mcp-server

Exposes the ExpenseBot knowledge base, FAQ, and feature docs as MCP resources. Useful for AI agents answering "does ExpenseBot support X?" type questions.

Source / issues / support

• Source: https://github.com/TotesMagotes/expensebot/tree/master/mcp-server-auth
• Issues: email [email protected]
• Complete setup chooser and remote/desktop instructions: https://www.expensebot.ai/mcp#choose-connection

Maintainer: adding or changing a tool

The stdio TOOLS[] catalog in src/index.js is the schema source of truth, but it is only one part of the release. A new MCP tool must also be registered in the main app's shared action policy, and a deliberate decision must be made about whether the same tool belongs in ExpenseBot's in-app chat.

Required workflow:

1. Add the TOOLS[] definition and matching handleTool() case here.
2. Run npm run sync-check and npm test; update the inventory and versioned package metadata when publishing.
3. Run npm run sync-tools from mcp-server-remote/ and commit the generated catalog.
4. Register the backend action in server/config/actionPolicy.js and the tool in server/config/toolPolicy.js, with explicit mcp and/or chat surfaces.
5. Verify remote TOOL_TO_ACTION, metadata/exclusions, main-route parity, and policy coverage tests.
6. For a chat-visible write, do not enable it until it has the durable confirmation adapter and result probe required by the canonical contract.

The complete bidirectional checklist and deployment matrix are in docs/architecture/mcp-and-chat-tool-surface.md. In particular, changing the main backend does not require republishing this npm package unless this package's schema, local dispatch, or transport also changed.

Publishing this package

Releases are automated through GitHub Actions OIDC trusted publishing — there is no long-lived npm token to manage.

• Workflow: .github/workflows/publish-mcp-server-auth.yml (runs on Node 22, the minimum an OIDC-capable npm needs).
• Trigger: a push to master that changes mcp-server-auth/package.json (i.e. a version bump), or a manual Run workflow (workflow_dispatch).
• It runs prepublishOnly (npm run sync-check + src/test.js), then npm publish authenticated via OIDC, which also attaches build provenance.
• It is idempotent: if the version in package.json is already on npm it skips the publish, so a manual run is a safe no-op dry run.

To cut a release: bump version in mcp-server-auth/package.json on master. The workflow publishes the new version automatically.

Trusted publishing is configured on npm (package Settings -> Trusted Publisher: GitHub Actions, repo TotesMagotes/expensebot, workflow publish-mcp-server-auth.yml). Do not hand-publish with a personal token — npm is removing direct-publish granular tokens in 2027, and OIDC is the supported path.

License

MIT