Recite MCP

recite-mcp

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

recite-mcp は Recite API 用の MCP サーバーです。スキャン、取引、インポート、バッチジョブ、プロジェクト、概要、Webhook、ルール、使用状況、エクスポートに関する Recite MCP のドキュメント化された機能をすべて提供するとともに、ローカル優先の帳簿管理を行いたいエージェント向けに、ローカルの台帳／メモリのワークフローも維持します。

インストール

エンドユーザー

推奨：

uvx recite-mcp

代替方法（pipx）：

pipx install recite-mcp

代替方法（pip）：

python -m pip install recite-mcp

コントリビューター

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

必須環境

https://recite.rivra.dev/settings/api で API キーを取得し（月 30 回まで無料でスキャンできます）、RECITE_API_KEY を設定してください（レシートの処理に必須です。サーバーはこのキーがなくても起動できるため、validate_setup() で不足しているものを確認できます）。

# Windows PowerShell
$env:RECITE_API_KEY="re_live_xxx"

# macOS/Linux
export RECITE_API_KEY="re_live_xxx"

任意のホームディレクトリの上書き設定：

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

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

MCP クライアントの設定

次の設定をコピーして貼り付けてください：

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

pipx または pip でインストールした場合は、次を使用してください：

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

トラブルシューティング

MCP Registry の所有権検証に失敗する

• 症状：Registry への公開時に、PyPI の所有権／README 検証エラーが返されます。
• 解決方法：パッケージに含める README に正確に次の行を残し、バージョンを上げてから、新しい PyPI リリースをアップロードして Registry に公開してください：mcp-name: io.github.rivradev/recite-mcp

RECITE_API_KEY が未設定または無効

• 症状：validate_setup() が missing_api_key を報告するか、API リクエストが拒否されます。
• 解決方法：MCP クライアントの env 設定（推奨）またはシェル環境で RECITE_API_KEY を設定してください。

uvx コマンドが見つからない

• 症状：ターミナルに uvx が認識されないと表示されます。
• 解決方法：まず uv をインストールするか、次のいずれかを使用してください：
  • pipx install recite-mcp
  • python -m pip install recite-mcp

インストール後に recite-mcp コマンドが見つからない

• 症状：pipx／pip でインストールした後、コマンドが認識されません。
• 解決方法：
  • pipx の場合：pipx ensurepath を実行してから、ターミナルを再起動してください。
  • pip の場合：モジュールのエントリーポイントを使用して実行してください：python -m recite_mcp.server

MCP クライアントは起動するが、ツールを利用できない

• 症状：サーバーは設定済みのように見えますが、ツール／リソースが一覧表示されません。
• 解決方法：
  • MCP 設定 JSON が有効であることを確認してください。
  • コマンドと引数がインストール方法（uvx と recite-mcp）に合っていることを確認してください。
  • 設定を変更した後、MCP クライアントを再起動してください。

PyPI からダウンロードできない（uvx／pip）

• 症状：ネットワーク／プロキシエラーにより、インストールまたは実行に失敗します。
• 解決方法：お使いの環境から PyPI にアクセスできることを確認してください（必要に応じてプロキシまたはカスタムインデックスを設定してください）。アクセス制限のあるネットワークを使用している場合は、PyPI を許可リストに追加するか、内部ミラーを使用する必要があります。

ローカルでの簡易検証（MCP クライアント不要）

• recite-mcp --validate（または uvx recite-mcp --validate）を実行すると、ローカル設定／ヘルス状態の JSON が出力されます。API キーが設定されている場合の終了コードは 0、設定されていない場合は 1 です。

主な機能

API ツール（合計 41 個）：

• スキャン — scan_receipt（ファイル、URL、base64、またはプレーンテキスト。エフェメラルモード）、get_scan
• 取引 — 作成、一覧表示（フィルター指定可）、取得、更新、削除、import_transactions（JSON リスト、CSV テキスト、または CSV ファイル）
• バッチスキャン — submit_batch_scans（1～20 件、非同期、Webhook 通知）、get_batch_scan_status、get_batch_scan_results
• プロジェクト — 一覧表示、作成、更新、削除
• サマリー — get_summary（期間、日付範囲、グループ化）
• Webhook — 作成、一覧表示、削除（transaction.created/updated/deleted、batch.completed）
• 照合 — create_reconciliation_link、list_reconciliation_links、update_reconciliation_link、delete_reconciliation_link、run_auto_match、get_reconciliation_summary、get_reconciliation_recommendations、export_reconciliation
• ルール — 作成、一覧表示、更新、削除（vendor_category、default_project、processing_preference）
• カテゴリー — get_categories（組み込み 17 件＋カスタム）、create_category、delete_category
• ベンダー — get_vendors、create_vendor、delete_vendor
• 使用状況 — get_usage（期間、内訳）
• エクスポート — export_transactions（CSV/JSON、任意でファイルに保存）

ローカルツール：

• process_receipt — スキャンと台帳への追記を 1 ステップで実行（任意の名前変更、ドライラン、カテゴリーのヒント）
• process_receipts_batch — 画像/PDF のディレクトリをスキャン（再帰処理、ドライランでのプレビュー）
• summarize_ledger、export_ledger、add_ledger_correction — ローカル CSV 台帳の管理
• update_memory、list_memory — エージェントへの指示を永続的に保存
• get_config、validate_setup — 設定の確認とヘルスチェック

リソース： recite://ledger、recite://memory、recite://health

ドキュメント

• ユーザーガイド：docs/user_guide.md