# io.github.TotesMagotes/mcp-server-auth (npm · @expensebot/mcp-server-auth)

Submit receipts, run income/P&L/mileage/subscription analytics, create reports in ExpenseBot.

- Trust score: 61/100 (medium)
- Change this week: +43
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@expensebot/mcp-server-auth`: 61/100 (this document), [markdown](https://verifymcp.io/servers/totesmagotes-mcp-server-auth/expensebot-mcp-server-auth.md), [page](https://verifymcp.io/servers/totesmagotes-mcp-server-auth/expensebot-mcp-server-auth)

## Channel facts

- Registry: `npm`
- Package: `@expensebot/mcp-server-auth`
- Version: `0.6.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 86/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (94 of 98), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 19/100
  - Repository check failed: the declared repository URL returned HTTP 404.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 2 days ago).
  - Security-disclosure policy not yet verified: we couldn't inspect the source repository.
- **Schema Quality & AI Usability**: 66/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 3939 tokens (~119/item across 33 items; 33 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 92/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 75% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add totesmagotes-mcp-server-auth -- npx -y @expensebot/mcp-server-auth
```

### Codex

```bash
codex mcp add totesmagotes-mcp-server-auth -- npx -y @expensebot/mcp-server-auth
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "totesmagotes-mcp-server-auth": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@expensebot/mcp-server-auth"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add totesmagotes-mcp-server-auth --command npx --arg -y --arg @expensebot/mcp-server-auth
```

### Hermes

```yaml
mcp_servers:
  totesmagotes-mcp-server-auth:
    command: "npx"
    args: ["-y", "@expensebot/mcp-server-auth"]
```

### Other

```json
{
  "mcpServers": {
    "totesmagotes-mcp-server-auth": {
      "command": "npx",
      "args": [
        "-y",
        "@expensebot/mcp-server-auth"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 61, +4)

- [functional improvement] Stability: unverified → 0.27

### 2026-08-02 (score 57, +42)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] License: unverified → pass
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Schema quality: unverified → good
- [functional] Licence: MIT

### 2026-08-01 (score 15, +1)

- [security improvement] Malware scan: unverified → pass
- [functional regression] Tool coverage: 100 → unverified

### 2026-07-31 (score 14, −24)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 38, +20)

- [functional improvement] Tool coverage: unverified → 100
- [functional] First check of Tool coverage: 75
- [functional] First check of Schema quality: unverified
- [functional] First check of Schema quality: fail
- [functional] First check of Schema quality: fail

### 2026-07-27 (score 18)

First indexed and scored.

## MCP tools (33)

### `search_expenses` (~135 tokens)

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

Input parameters:

- `categories` (array): Filter by expense categories (e.g., ['Travel', 'Meals'])
- `dateRange` (object): Time period filter
- `limit` (integer): Max results (default 20)
- `maxAmount` (number): Maximum expense amount
- `merchants` (array): Filter by merchant names (e.g., ['Uber', 'Starbucks'])
- `minAmount` (number): Minimum expense amount
- `tags` (array): Filter by tags

### `get_spending_summary` (~259 tokens)

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? } }.

Input parameters:

- `categories` (array)
- `dateRange` (object)
- `groupBy` (string)
- `metric` (string)
- `query` (string): Natural language question (e.g., 'how much did I spend in March', 'rental income by property')

### `get_deep_analytics` (~109 tokens)

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.

Input parameters:

- `dateRange` (object)
- `query` (string, required): The analytics question to answer

### `create_report` (~83 tokens)

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

Input parameters:

- `categories` (array)
- `dateRange` (object, required): Time period for the report (required)
- `shareWith` (array): Email addresses to share the report with
- `tags` (array)
- `title` (string): Custom report title

### `list_reports` (~49 tokens)

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

Input parameters:

- `filter` (string)
- `limit` (integer)
- `page` (integer)

### `get_report_details` (~41 tokens)

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

Input parameters:

- `reportId` (string, required): The report/spreadsheet ID

### `share_report` (~38 tokens)

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

Input parameters:

- `recipients` (array, required)
- `reportId` (string, required)

### `check_compliance` (~38 tokens)

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

Input parameters:

- `reportId` (string, required): Report ID to check

### `fix_compliance` (~57 tokens)

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

Input parameters:

- `action` (string, required)
- `reportId` (string, required)
- `value` (string, required): The value to apply

### `check_tax_deductibility` (~162 tokens)

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).

Input parameters:

- `category` (string)
- `merchant` (string)
- `query` (string, required): Deductibility question (e.g., 'is Uber tax deductible', 'home office write-off rules')

### `search_knowledge` (~49 tokens)

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

Input parameters:

- `limit` (integer)
- `query` (string, required): Search terms

### `submit_receipt` (~135 tokens)

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.

Input parameters:

- `filename` (string): Optional filename (e.g., 'lunch_receipt.jpg')
- `mimeType` (string): MIME type of the file (default: image/jpeg)
- `photo` (string, required): Base64-encoded image or PDF data (JPEG, PNG, HEIC, WebP, or PDF). Max 15MB.

### `add_cash_expense` (~134 tokens)

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

Input parameters:

- `category` (string, required): Expense category
- `city` (string): City/location
- `currency` (string): Currency code (default: USD)
- `date` (string, required): Expense date (YYYY-MM-DD)
- `merchant` (string, required): Merchant/vendor name
- `notes` (string): Notes or description
- `subtotal` (number): Subtotal before tax
- `tax` (number): Tax amount
- `tip` (number): Tip amount
- `total` (number, required): Total amount

### `parse_expense` (~86 tokens)

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, ...}

Input parameters:

- `text` (string, required): Natural language expense (e.g., "Coffee at Starbucks $6.50 yesterday")

### `process_gmail_receipts` (~95 tokens)

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.

Input parameters:

- `accountEmail` (string): Optional: which Gmail account to use (for users with multiple linked accounts)
- `emailIds` (array, required): Gmail message IDs to process as receipts

### `scan_gmail` (~135 tokens)

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.

Input parameters:

- `accountEmail` (string): Optional: which Gmail account to scan
- `endDate` (string): Optional: explicit end date (YYYY-MM-DD)
- `lookbackDays` (integer): How many days back to scan (default 60, max depends on subscription)
- `startDate` (string): Optional: explicit start date (YYYY-MM-DD) instead of lookbackDays

### `get_signup_link` (~84 tokens)

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.

Input parameters:

- `utmSource` (string): Optional UTM source (defaults to 'mcp')

### `add_mileage_entry` (~218 tokens)

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.

Input parameters:

- `category` (string): Override the user's default mileage category (optional)
- `city` (string): City (optional)
- `date` (string): Trip date (YYYY-MM-DD). Defaults to today.
- `destination` (string): Destination address or location (optional)
- `distance` (number, required): Distance traveled in the user's configured unit (miles or km)
- `notes` (string)
- `purpose` (string, required): Business purpose / description of the trip (e.g., 'Client meeting at 1234 Main St')
- `roundTrip` (boolean): If true, doubles the distance (return trip)
- `tag` (string): Tag for client/project attribution (optional)

### `add_income` (~219 tokens)

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.

Input parameters:

- `amount` (number, required): Income amount (>0)
- `category` (string): Income category (optional)
- `currency` (string): Currency code (default: home currency)
- `date` (string): Income date (YYYY-MM-DD). Defaults to today.
- `description` (string): What the income was for
- `fees` (number): Processor/transfer fees deducted
- `notes` (string)
- `paymentMethod` (string, required): How you got paid (e.g., 'Cash', 'Check', 'Stripe', 'Bank Transfer', 'Venmo')
- `reference` (string): Invoice or transaction reference
- `source` (string, required): Who paid you (client name, customer, etc.)
- `tag` (string): Tag for client/project attribution
- `taxCollected` (number): Sales tax/GST/HST collected

### `list_categories` (~61 tokens)

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_tags` (~63 tokens)

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.

### `get_income_summary` (~297 tokens)

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? } }.

Input parameters:

- `dateRange` (object)
- `groupBy` (string): How to group the breakdown
- `incomeTagPrefix` (string): Optional tag-prefix shortcut (e.g., 'Prop –' for rental income, 'Client –' for client billings, 'Wedding –' for events). When set, the tool filters to income rows tagged with this prefix.
- `query` (string): Natural language income question (e.g., 'income YTD by source', 'rental income last month')

### `get_pnl` (~189 tokens)

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? } }.

Input parameters:

- `dateRange` (object)
- `query` (string): Natural language P&L question (e.g., 'P&L for Q1 2025', 'am I profitable')

### `get_per_tag_pnl` (~240 tokens)

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.

Input parameters:

- `dateRange` (object)
- `query` (string): Natural language per-tag P&L question
- `tagPrefix` (string): Optional prefix to limit which tags are bucketed (e.g., 'Prop –' for properties only, 'Client –' for clients only). When omitted, all tags are included.

### `list_income_categories` (~79 tokens)

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.).

### `get_recent_activity` (~141 tokens)

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).

Input parameters:

- `actionId` (string): Optional: filter to a single tool/action name
- `limit` (integer)
- `sinceDays` (integer): Only show actions from the last N days (default 7)

### `get_mileage_summary` (~170 tokens)

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? } }.

Input parameters:

- `dateRange` (object)
- `groupBy` (string): How to group the breakdown
- `query` (string): Natural language mileage question (e.g., 'mileage this year', 'miles driven for Acme client')

### `get_subscription_audit` (~144 tokens)

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? } }.

Input parameters:

- `dateRange` (object)
- `focus` (string): Narrow the audit to a single category (default: all)
- `query` (string): Natural language subscription question (e.g., 'find duplicate subscriptions', 'price increases this year')

### `get_expense_by_id` (~106 tokens)

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.

Input parameters:

- `expenseId` (string): ExpenseBot expense ID (column J)
- `rowNumber` (integer): 1-indexed sheet row (row 1 is headers, so ≥ 2)

### `export_report` (~81 tokens)

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.

Input parameters:

- `reportId` (string, required): Report ID from list_reports

### `get_pricing` (~60 tokens)

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.

### `check_feature` (~80 tokens)

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.

Input parameters:

- `feature` (string, required): Feature or integration to check (e.g., 'Xero', 'mileage tracking', 'Plaid')

### `start_trial_link` (~102 tokens)

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.

Input parameters:

- `utmCampaign` (string): UTM campaign override (default: 'ai-assistant')
- `utmSource` (string): UTM source override (default: 'mcp')

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/totesmagotes-mcp-server-auth/expensebot-mcp-server-auth#diagnostics

## Score history

- 2026-08-03: 61
- 2026-08-02: 57
- 2026-08-01: 15
- 2026-07-31: 14
- 2026-07-30: 38
- 2026-07-28: 18
- 2026-07-27: 18

## Links

- npm package: https://www.npmjs.com/package/@expensebot/mcp-server-auth
- Socket report: https://socket.dev/npm/package/@expensebot/mcp-server-auth
- Changelog RSS feed: https://verifymcp.io/servers/totesmagotes-mcp-server-auth/expensebot-mcp-server-auth/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/totesmagotes-mcp-server-auth/expensebot-mcp-server-auth/changelog.json
- HTML version of this page: https://verifymcp.io/servers/totesmagotes-mcp-server-auth/expensebot-mcp-server-auth