@hoagsmedia/frugr-mcp

A thin MCP bridge to your frugr books. Point your own AI client — Cursor, Claude Desktop, Claude Code, or any MCP-capable app — at your accounting data and ask questions in plain language.

What it does

It exposes read tools over stdio and forwards each call to the frugr API using your Personal Access Token:

| Tool | Returns | | --------------------------------------- | ---------------------------------------------------------- | | get_profit_loss | Income, expenses, net, and per-category totals for a year | | search_transactions | Ledger transactions by text, date range, and/or category | | list_categories | Chart-of-accounts category names and kinds | | summarize_transactions | Transaction totals, rollups, and largest matching rows | | compare_periods | Period-over-period transaction totals and counts | | compare_receipts_to_bank_transactions | Receipt-backed rows vs matching bank rows | | get_open_invoices | Outstanding receivables with balances by client | | get_open_bills | Outstanding payables with due dates and vendor balances | | get_reconciliation_status | Account reconciliation freshness and uncleared counts | | get_time_mileage_summary | Billable time and mileage trip summaries | | get_business_snapshot | Compact receivables, payables, spend, and cleanup snapshot | | find_bookkeeping_issues | Uncategorized rows, missing receipts, and duplicates |

Write-shaped work goes through frugr's review queue — proposal tools (including import_receipt_file, which reads a receipt from your machine and files it for approval) never write to the ledger directly; approval always happens in the frugr app.

The bridge holds no credentials of its own and runs your AI client's model under your subscription — frugr is only the data provider. Your token scopes access to a single company and can be revoked at any time.

Setup

1. In frugr, go to Settings → External AI apps (MCP) and create a token (owner/admin only). Copy it — it's shown once.
2. Add the bridge to your client's MCP config:

{
	"mcpServers": {
		"frugr": {
			"command": "npx",
			"args": ["-y", "@hoagsmedia/frugr-mcp@latest"],
			"env": {
				"FRUGR_API_URL": "https://frugr.app",
				"FRUGR_API_TOKEN": "frugr_pat_your_token_here"
			}
		}
	}
}

• Claude Desktop: Settings → Developer → Edit Config.
• Cursor: .cursor/mcp.json in your project (or the global equivalent).
• Claude Code: claude mcp add or your mcp.json.

Requires Node.js 18+.

Environment

| Variable | Required | Default | Notes | | ----------------- | -------- | ------------------- | -------------------------- | | FRUGR_API_TOKEN | yes | — | Your Personal Access Token | | FRUGR_API_URL | no | https://frugr.app | Your frugr origin |

Verifying a token

curl -H "Authorization: Bearer frugr_pat_…" https://frugr.app/api/mcp
# → {"ok":true,"transport":"frugr-mcp","tools":["get_profit_loss", ...]}

Security

• Reads query your books; write-shaped tools only file proposals into the review queue — nothing touches the ledger without approval in the app.
• Org-scoped: a token resolves to exactly one company server-side; the tools never accept a tenant id from the client.
• Rate-limited and audited per token on the frugr side.
• Revoke a token instantly from Settings → External AI apps (MCP).

Publishing (maintainers)

Single package, published from mcp-server/, under the hoagsmedia npm org.

1. Bump version in mcp-server/package.json and add a CHANGELOG.md entry.
2. Merge to main, then publish before the pinned Settings copy reaches prod:
   • GitHub Actions: run workflow Publish MCP server (workflow_dispatch), or
   • Tag: push frugr-mcp-vX.Y.Z.
3. Requires NPM_TOKEN in repo secrets — use an npm Granular Access Token with type Automation (publish to @hoagsmedia). Legacy/read-write tokens with account 2FA fail CI with EOTP; automation tokens skip OTP.

Local dry run:

cd mcp-server && npm publish --dry-run

Smoke after publish (stderr banner; needs a valid PAT — or use Settings → Test connection):

FRUGR_API_TOKEN=frugr_pat_… npx -y @hoagsmedia/[email protected] 2>&1 | head -1
# → [frugr-mcp] connected to …

History

@hoagsmedia/frgur-mcp-server (the original, misspelled package name) was retired from npm in July 2026 — this package is the same bridge. If an old config references it, switch the package name to @hoagsmedia/frugr-mcp; env vars and behavior are identical.