financeops-mcp

v1.0.0

Published

3 months ago

Unified financial intelligence MCP server — Stripe + Xero

0High
0Medium
0Low

Financial intelligence for AI coding agents. Connect Stripe, Exact Online, Moneybird, QuickBooks Online, or FreshBooks, then ask your AI agent anything about your business finances — health checks, P&L, cash flow forecasts, reconciliation, and anomaly detection.

Quick Start · Tools · Pro Features · Security · Architecture

See it in action

 Agent     "What's our financial health right now?"

 FinanceOps  financial_health({ providers: ["stripe"] })

 Result:

 Financial Health Report
 ──────────────────────────────────────────────────
 MRR              $12,450.00     ▲ +8.3% vs last month
 ARR              $149,400.00
 Burn Rate        $4,200.00/mo
 Runway           29.6 months
 Churn Rate       2.1%
 Active Customers 187

 Stripe balance:  $8,320.50 (available)
                  $1,200.00 (pending)

 Status: HEALTHY  ✓
 Generated in 340ms

 Agent     "Generate a P&L for this quarter"

 FinanceOps  generate_pnl({
               providers: ["stripe"],
               period: "quarter",
               date_from: "2026-01-01",
               date_to: "2026-03-31"
             })

 Result:

 Profit & Loss — Q1 2026
 ──────────────────────────────────────────────────
 Revenue
   Stripe Payments     $34,210.00
   Total Revenue       $34,210.00

 Expenses
   SaaS & Subscriptions  $1,840.00
   Payroll               $9,000.00
   Other                 $2,100.00
   Total Expenses       $12,940.00

 Net Profit             $40,210.00   (75.7% margin)

Architecture

graph LR
    A["AI Agent<br/>(Claude, Cursor, Windsurf)"] -->|MCP Protocol| B["FinanceOps MCP"]
    B --> C["Stripe API<br/>(Payments & Billing)"]
    B --> D["Exact Online / Moneybird / QuickBooks / FreshBooks<br/>(Accounting & Invoices)"]
    B --> E["Analysis Engine<br/>(P&L · Cash Flow · Anomaly)"]
    B --> F["Audit Trail<br/>(SQLite)"]

    style A fill:#1f2937,stroke:#10b981,color:#f0f6fc
    style B fill:#0d1117,stroke:#10b981,stroke-width:2px,color:#10b981
    style C fill:#0a1f16,stroke:#635bff,color:#f0f6fc
    style D fill:#0a1f16,stroke:#13b5ea,color:#f0f6fc
    style E fill:#0a1f16,stroke:#10b981,color:#f0f6fc
    style F fill:#161b22,stroke:#30363d,color:#8b949e

Quick Start

npx financeops-mcp

Set your provider credentials as environment variables:

# Stripe
export STRIPE_SECRET_KEY=sk_live_...

# Exact Online (OAuth2 — register at apps.exactonline.com)
export EXACT_CLIENT_ID=...
export EXACT_CLIENT_SECRET=...
export EXACT_REFRESH_TOKEN=...
export EXACT_DIVISION=12345

# Moneybird (token — create at moneybird.com/user/applications/new)
export MONEYBIRD_TOKEN=...
export MONEYBIRD_ADMINISTRATION_ID=...

# QuickBooks Online (OAuth2 — register at developer.intuit.com)
export QUICKBOOKS_ACCESS_TOKEN=...
export QUICKBOOKS_REALM_ID=...           # Company ID from Intuit Developer portal
# export QUICKBOOKS_SANDBOX=true         # Optional: use sandbox API

# FreshBooks (OAuth2 — register at developer.freshbooks.com)
export FRESHBOOKS_ACCESS_TOKEN=...
export FRESHBOOKS_ACCOUNT_ID=...         # Account ID from FreshBooks

Add to your claude_desktop_config.json:

macOS / Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "financeops": {
      "command": "npx",
      "args": ["financeops-mcp"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_live_..."
      }
    }
  }
}

Add to .cursor/rules/mcp_servers.json in your project root:

{
  "mcpServers": {
    "financeops": {
      "command": "npx",
      "args": ["financeops-mcp"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_live_..."
      }
    }
  }
}

Open settings (Cmd+Shift+P / Ctrl+Shift+P then search "MCP") and add:

{
  "mcpServers": {
    "financeops": {
      "command": "npx",
      "args": ["financeops-mcp"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_live_..."
      }
    }
  }
}

Set the PRO_LICENSE environment variable to unlock premium analysis tools:

{
  "mcpServers": {
    "financeops": {
      "command": "npx",
      "args": ["financeops-mcp"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_live_...",
        "PRO_LICENSE": "your-license-key"
      }
    }
  }
}

Or from the command line:

PRO_LICENSE=your-license-key npx financeops-mcp

Tools

Free Tools (6)

| Tool | Description | |:-----|:------------| | list_transactions | Fetch paginated transactions from Stripe with date range and status filters | | get_balances | Get current account balances — Stripe available/pending | | list_invoices | Fetch invoices with status filtering (paid, pending, overdue) and date range | | revenue_summary | Calculate revenue metrics for a period — total, average transaction, top customers | | expense_tracker | Categorize and summarize expenses by type with period filtering | | financial_health | Quick health check across providers — MRR, ARR, burn rate, runway, churn rate |

Pro Features (6)

| Tool | Description | |:-----|:------------| | generate_pnl | Full Profit & Loss statement from Stripe data for any period (PRO) | | cash_flow_forecast | 3/6/12-month cash flow forecast — conservative, realistic, and optimistic scenarios (PRO) | | reconcile | Cross-reference transactions across providers to find discrepancies (PRO) | | detect_anomalies | Statistical anomaly detection — flag unusual transactions, spikes, and drops (PRO) | | tax_summary | VAT/sales tax calculation and period summary by jurisdiction (PRO) | | multi_currency_report | Consolidated multi-currency reporting — converts balances, income, and expenses to base currency with live or fallback FX rates (PRO) |

Feature Comparison

Analysis Algorithms

P&L Generation

Aggregates income transactions (charges, refunds) and categorized expenses from connected providers, produces a structured statement with gross profit, operating expenses, and net profit with margin percentages.

Cash Flow Forecasting

Uses a weighted moving average over the last 3 months of historical data (weights: 1, 2, 3 oldest to newest). Applies a linear trend multiplier derived from first-vs-last net cash flow change. Outputs three scenarios:

| Scenario | Income Adjustment | Use Case | |:---------|:------------------|:---------| | Conservative | −20% | Worst-case planning, fundraising | | Realistic | Baseline trend | Default projection | | Optimistic | +20% | Best-case, growth planning |

Minimum 3 months of historical data required.

Reconciliation

Cross-references transactions across connected providers using fuzzy amount matching (±1% tolerance for currency conversion). Flags unmatched, duplicate, and reversed transactions. Requires at least 2 connected providers (Exact Online and Moneybird coming soon).

Anomaly Detection

Category-average variance analysis across all transactions. Flags amounts that deviate significantly from the per-category average. Configurable sensitivity:

Low — flags transactions >3× category average
Medium — flags >2× category average (default)
High — flags >1.5× category average

Supported Providers

Note: Xero is intentionally excluded due to restrictive AI/ML clauses in their developer terms (as of late 2025).

Credentials

# Stripe — secret key from dashboard.stripe.com/apikeys
STRIPE_SECRET_KEY=sk_live_...

# Exact Online — register app at apps.exactonline.com
EXACT_CLIENT_ID=...
EXACT_CLIENT_SECRET=...
EXACT_REFRESH_TOKEN=...        # Rotates automatically on each use
EXACT_DIVISION=12345           # Numeric company/administration ID
# EXACT_TOKEN_FILE=.exact-token.json  # Optional: persist rotated refresh tokens

# Moneybird — create token at moneybird.com/user/applications/new
MONEYBIRD_TOKEN=...
MONEYBIRD_ADMINISTRATION_ID=...  # Numeric administration ID

# QuickBooks Online — register app at developer.intuit.com
QUICKBOOKS_ACCESS_TOKEN=...       # OAuth2 access token
QUICKBOOKS_REALM_ID=...           # Company ID from Intuit Developer portal
# QUICKBOOKS_SANDBOX=true         # Optional: use sandbox API (sandbox-quickbooks.api.intuit.com)

# FreshBooks — register app at developer.freshbooks.com
FRESHBOOKS_ACCESS_TOKEN=...       # OAuth2 Bearer token
FRESHBOOKS_ACCOUNT_ID=...         # Account ID from FreshBooks settings

Limitations:

Moneybird balances: Not available via API. Balance data requires bank feed integration.
Moneybird transactions: Only bank-linked mutations are returned. Manual transactions may not appear.
Exact Online rate limit: 60 requests/minute per division. The adapter handles retry automatically.
Exact Online refresh tokens: Each token refresh invalidates the previous token. Set EXACT_TOKEN_FILE to persist across restarts.
QuickBooks access tokens: OAuth2 access tokens expire after 1 hour. Refresh tokens externally or use Intuit's OAuth2 playground for development.
QuickBooks rate limit: 500 requests/minute. The adapter handles retry automatically via fetchWithRetry.
FreshBooks access tokens: OAuth2 access tokens expire after a set period. Refresh tokens externally using the FreshBooks OAuth2 flow.
FreshBooks balances: Not available via API. The adapter returns an empty array for balance queries.

Security

FinanceOps MCP is read-only by design. It calls provider APIs with read scopes only — it cannot move money, create invoices, or modify accounting records.

| Principle | Details | |:----------|:--------| | Read-only by default | All tools only read data — no write operations, no fund transfers | | No stored credentials | API keys are passed via environment variables and never written to disk | | No telemetry | Zero analytics, zero phone-home. Your financial data stays local | | Audit trail | Every tool call is logged locally in SQLite with timestamp, tool name, provider, and success/failure | | Least privilege | Use restricted Stripe keys (read-only) |

Best Practices

# Use restricted Stripe keys — create at dashboard.stripe.com/apikeys
# Toggle off all write permissions, keep only: Read balance, Read charges, Read invoices

# Use environment variables — never hardcode API keys
STRIPE_SECRET_KEY=sk_restricted_... npx financeops-mcp

# Rotate credentials regularly
# Exact Online tokens rotate — set EXACT_TOKEN_FILE for persistence across restarts

Pro License

Unlock P&L generation, cash flow forecasting, reconciliation, anomaly detection, tax summaries, and multi-currency reporting.

Get your license:

Gumroad — Instant delivery
MCPize — MCP marketplace

# Activate
export PRO_LICENSE=your-license-key
npx financeops-mcp

# Or inline
PRO_LICENSE=your-license-key npx financeops-mcp

Built by Craftpipe — AI-powered developer tools

GitHub · npm · Support