recite-mcp

recite-mcp

mcp-name: io.github.rivradev/recite-mcp

recite-mcp is an MCP server for the Recite API. It provides the full documented Recite MCP surface for scans, transactions, imports, batch jobs, projects, summaries, webhooks, rules, usage, and exports, while preserving the local ledger/memory workflow for agents that want local-first bookkeeping.

Install

End users

Recommended:

uvx recite-mcp

Alternative (pipx):

pipx install recite-mcp

Alternative (pip):

python -m pip install recite-mcp

Contributors

python -m pip install -e .[dev]
pytest -q
python -m recite_mcp.server

Required Environment

Get an API key at https://recite.rivra.dev/settings/api (includes 30 free scans per month), then set RECITE_API_KEY (required to process receipts; server can still start without it so validate_setup() can report what's missing):

# Windows PowerShell
$env:RECITE_API_KEY="re_live_xxx"

# macOS/Linux
export RECITE_API_KEY="re_live_xxx"

Optional home override:

# Windows PowerShell
$env:RECITE_HOME="C:\path\to\recite-home"

# macOS/Linux
export RECITE_HOME="$HOME/.config/recite"

MCP Client Config

Copy-paste this config:

{
  "mcpServers": {
    "recite": {
      "command": "uvx",
      "args": ["recite-mcp"],
      "env": {
        "RECITE_API_KEY": "re_live_xxx"
      }
    }
  }
}

If installed via pipx or pip, use:

{
  "mcpServers": {
    "recite": {
      "command": "recite-mcp",
      "args": [],
      "env": {
        "RECITE_API_KEY": "re_live_xxx"
      }
    }
  }
}

Troubleshooting

MCP Registry ownership validation failed

• Symptom: Registry publish returns a PyPI ownership/README validation error.
• Fix: keep this exact line in packaged README: mcp-name: io.github.rivradev/recite-mcp, then bump version and upload new PyPI release before publishing to Registry.

RECITE_API_KEY missing or invalid

• Symptom: validate_setup() reports missing_api_key or API requests are rejected.
• Fix: set RECITE_API_KEY in MCP client env config (preferred) or shell environment.

uvx command not found

• Symptom: terminal says uvx is not recognized.
• Fix: install uv first, or use one of the alternatives:
  • pipx install recite-mcp
  • python -m pip install recite-mcp

recite-mcp command not found after install

• Symptom: command not recognized after pipx/pip install.
• Fix:
  • For pipx: run pipx ensurepath, then reopen terminal.
  • For pip: run with module entrypoint: python -m recite_mcp.server

MCP client starts but tools are unavailable

• Symptom: server appears configured but no tools/resources are listed.
• Fix:
  • Confirm MCP config JSON is valid.
  • Confirm command and args match your install method (uvx vs recite-mcp).
  • Restart MCP client after config changes.

Can't download from PyPI (uvx/pip)

• Symptom: install/run fails with network/proxy errors.
• Fix: ensure your environment can reach PyPI (or configure your proxy / custom index). If you're on a locked-down network, you may need to allowlist PyPI or use an internal mirror.

Quick local validation (no MCP client)

• Run recite-mcp --validate (or uvx recite-mcp --validate) to print local config/health JSON. Exit code is 0 if an API key is present, otherwise 1.

Main Features

API tools (41 total):

• Scans — scan_receipt (file, URL, base64, or raw text; ephemeral mode), get_scan
• Transactions — create, list (with filters), get, update, delete, import_transactions (JSON list, CSV text, or CSV file)
• Batch scans — submit_batch_scans (1–20 items, async, webhook notification), get_batch_scan_status, get_batch_scan_results
• Projects — list, create, update, delete
• Summaries — get_summary (period, date range, group-by)
• Webhooks — create, list, delete (transaction.created/updated/deleted, batch.completed)
• Reconciliation — create_reconciliation_link, list_reconciliation_links, update_reconciliation_link, delete_reconciliation_link, run_auto_match, get_reconciliation_summary, get_reconciliation_recommendations, export_reconciliation
• Rules — create, list, update, delete (vendor_category, default_project, processing_preference)
• Categories — get_categories (17 built-in + custom), create_category, delete_category
• Vendors — get_vendors, create_vendor, delete_vendor
• Usage — get_usage (period, breakdown)
• Exports — export_transactions (CSV/JSON, optional file save)

Local tools:

• process_receipt — scan + ledger append in one step (optional rename, dry-run, category hint)
• process_receipts_batch — scan a directory of images/PDFs (recursive, dry-run preview)
• summarize_ledger, export_ledger, add_ledger_correction — local CSV ledger management
• update_memory, list_memory — persistent agent instruction storage
• get_config, validate_setup — configuration inspection and health check

Resources: recite://ledger, recite://memory, recite://health

Documentation

• User guide: docs/user_guide.md