io.github.TotesMagotes/mcp-server-auth

Add an expense without a receipt (cash purchase, tip, etc.). Writes directly to the user's expense spreadsheet.

Log an income entry manually (cash, check, Stripe payout, etc.). Writes to the Income tab of the user's expense spreadsheet. Useful for income that isn't auto-detected from Gmail or Plaid.

Log a business mileage trip in ExpenseBot. Useful for realtors, consultants, contractors, and anyone who drives for work. Requires the user to have configured their mileage rate (cents/km or cents/mi) and unit (mi/km) in ExpenseBot Settings. The trip writes a row to their expense spreadsheet with the calculated dollar value.

Check an expense report for compliance issues (missing business purpose, policy violations, etc.).

Check whether ExpenseBot supports a specific feature ('does ExpenseBot support X', 'can it integrate with Y'). Searches the public knowledge base and returns a confidence-scored answer + related questions. Works with or without authentication.

Look up whether a specific expense type or purchase is tax-DEDUCTIBLE (business write-off rules) based on the user's country/jurisdiction. This is a deductibility *advice* tool — use it for questions like 'is Uber deductible', 'can I write off home office', 'are client dinners 50% or 100%'. Do NOT use it for questions about tax REFUNDS received as income (use get_spending_summary with a 'tax refunds' query for those — they're routed to the Income tab, not deduction rules).

Create an expense report from filtered expenses. Returns the report ID and summary. Can optionally share with recipients.

Get download URLs for an expense report. Returns the Google Sheets view URL plus direct PDF / CSV / XLSX export URLs. The user needs to be signed into the Google account that owns the report to download (no separate auth from the AI client). Use list_reports first to find the reportId.

Bulk-fix compliance issues in a report (e.g., apply the same business purpose to all flagged expenses).

Run deeper, multi-step analytics on the user's expenses. Use for explanatory questions like 'why did my spending increase' or 'compare Q1 vs Q2'. Takes 10-30 seconds (runs as a background job, polled automatically). Returns: { message, data: { ..., sampleMeta? } } where sampleMeta.isTruncated indicates whether the agent saw the full dataset.

Fetch a single expense row by its sheet row number or by its ExpenseBot expenseId (the value in column J). Returns the row's headers + values + a labeled {header → value} map so you can refer to a specific expense the user mentioned. Read-only.

Get income totals, breakdowns, and analytics from the Income tab. Covers Schedule C / T2125 income, Schedule B drill-in (interest, dividends, tax refunds, security deposits), rental income, and per-source / per-payment-method / per-category / per-month / per-tag breakdowns. Schedule-C-style category exclusions match year-end T6 routing (security deposits, refunds excluded from taxable totals). Examples: 'income YTD', 'income by source', 'rental income by property', 'interest income this year', 'dividends YTD', 'tax refunds 2024', 'income this year vs last' (YoY). Supports period comparison phrasing — YoY ('vs last year'), MoM ('vs last month'), QoQ ('Q1 vs Q2'), same-month-prev-year. Returns: { message, data: { total, breakdown?, comparison?, sampleMeta? } }.

Mileage analytics — totals, breakdowns by month / client / purpose / category, plus deduction framing (cents-per-mile or cents-per-km × distance, country-aware IRS / CRA rates). Examples: 'mileage this year', 'miles driven for Acme', 'mileage by month', 'mileage deduction estimate', 'business miles last quarter'. Supports YoY / MoM / QoQ comparison phrasing. Returns: { message, data: { totalDistance, deductionEstimate?, breakdown?, comparison?, sampleMeta? } }.

Per-tag P&L — revenue, cost, profit, and margin grouped by tag (per-client, per-property, per-event, per-realtor-deal). Requires both income AND expense rows to be tagged with matching labels. Common tag-prefix shortcuts: 'Prop –' (rentals), 'Client –' (client billings), 'Wedding –' (events), 'Realtor –' (real estate deals). Examples: 'per-tag P&L this year', 'profit by client', 'profit by property', 'profit on the Smith wedding', 'per-client P&L this year vs last' (YoY). Supports YoY / MoM / QoQ comparison phrasing. Margin renders as multiplier in loss territory. Defaults to year-to-date if no date range given.

Compute Profit & Loss (P&L / net income / margin) by combining the Income tab with expense tabs. Examples: 'am I profitable this year', 'P&L for Q1', 'net income last quarter', 'what's my margin', 'P&L this year vs last' (YoY). Supports period comparison — YoY, MoM, QoQ, same-month-prev-year. Margin renders as multiplier in loss territory ('expenses 5.4× revenue') so the user gets a readable signal instead of '-436.9% margin'. Returns: { message, data: { revenue, expenses, netIncome, margin, comparison?, sampleMeta? } }.

Get current ExpenseBot pricing for all plans (Free Trial, Standard, Pro Add-On, Deep Scan, Accountants). Useful when the user asks 'how much does this cost' or 'what's the difference between plans'. Works with or without authentication.

Show what the user (or their AI assistants) has recently done in ExpenseBot via this MCP server: which tools were called, when, with what arguments, and whether they succeeded. Useful for ambient questions like 'what did I do this week', 'did my last receipt submission work', or to give the user transparency into AI-assisted actions. Returns the most recent N entries from the audit log (default 20, max 100).

Get full details of a specific expense report including all expenses, totals, and compliance status.

Get the ExpenseBot signup link. Use this when the user doesn't have an account yet, or when their MCP token is missing/expired and they need to sign up or get a new token. Returns a signup URL with a 60-day free trial — no credit card required.

Unified analytics endpoint — handles expenses, income, P&L, per-tag P&L (per-client / per-property / per-event), Schedule B drill-in (interest, dividends, tax refunds, security deposits), mileage, and subscription audits in ONE tool. Examples: 'how much did I spend last month', 'income YTD', 'rental income by property', 'P&L for Q1', 'profit by client', 'mileage this year', 'recurring subscriptions', 'price increases', 'duplicate subscriptions', 'trial conversions'. Supports period comparison phrasing — 'this year vs last' (YoY), 'vs last month' (MoM), 'Q1 vs Q2' (QoQ), same-month-prev-year. Margin renders as multiplier ('expenses 5.4× revenue') when in loss territory. Returns: { message, data: { total, breakdown?, comparison?, sampleMeta? } }.

Subscription audit — wraps the Subscription Auditor engine to find recurring charges, duplicates, price increases, and trial-conversion suspects in the user's expenses. Examples: 'recurring subscriptions', 'duplicate subscriptions', 'price increases', 'trial conversions', 'subscriptions over $20/month'. Returns: { message, data: { recurring, duplicates, priceIncreases, trialConversions, totalMonthlyCost, sampleMeta? } }.

List the user's configured expense categories and billing accounts. Use this BEFORE calling tools that need a category (add_cash_expense, add_mileage_entry, create_report) so you pass the user's actual category names, not guesses. Returns the live list from their spreadsheet.

List the user's configured income categories (mirrors list_categories for the Income tab). Use this BEFORE calling add_income with a category so you pass the user's actual income category names, not guesses. Returns the canonical INCOME_CATEGORIES enum (Service Revenue, Product Sales, Rental Income, Interest Income, Dividend Income, Tax Refund, Other Income, etc.).

List the user's expense reports with pagination. Filter by status (All, Draft, Submitted, Shared).

List the user's configured tags. Tags are used for client/project attribution (e.g., 'Client: Acme', 'Q1 Trip', 'Property: 123 Main'). Use this BEFORE calling tools that filter or assign tags so you pass valid tag names, not guesses.

Parse a natural language expense description into structured fields. Does NOT add the expense — just returns the parsed fields for review. Example: "Lunch at Chipotle $15.50 today" → {merchant: "Chipotle", total: 15.50, ...}

Process specific Gmail emails as receipts. Pass Gmail message IDs and they'll be converted to PDF, extracted by AI, and added to the user's expense spreadsheet. Max 25 emails per request. Requires Gmail to be connected in ExpenseBot settings.

Trigger a background Gmail scan to discover and process receipt emails. Runs asynchronously — returns immediately, user gets an email summary when done. Like clicking "Find Receipts in Gmail" in the UI. Default: scans last 60 days.

Search and filter the user's expenses. Returns matching expense rows from their spreadsheet. Filter by category, merchant, date range, amount, or tags.

Search the ExpenseBot knowledge base for help articles and how-to guides. Use when the user asks about ExpenseBot features.

Share an expense report with one or more email addresses for review or approval.

Get a UTM-tagged signup URL for the 60-day free trial (no credit card required). Use this when an unauthenticated AI conversation wants to send the user to sign up. Returns a URL with attribution tags so we can track AI-assistant referrals.

Submit a photo or PDF of a receipt for processing. The receipt image is sent as base64, validated, uploaded to cloud storage, and processed by AI to extract vendor, amount, date, tax, and category. The expense appears in the user's spreadsheet within 30 seconds.