bookie

bookie

フリーランサーや家主の帳簿を管理する MCP サーバーです。QuickBooks の代わりに、Claude や GPT から操作できます。

LLM に銀行明細のインポート、支出の分類、月次の照合、Schedule C の作成を依頼できます。Bookie はその下で正確な複式簿記の台帳を提供するため、モデルは即興で作り上げたスプレッドシートではなく、実際の数値をもとに推論できます。

こんな方におすすめです： Claude や GPT を日常的に使っている個人事業主、フリーランサー、賃貸物件の所有者で、5 分ほどのセットアップに抵抗がなく、正確な帳簿を付けたい方。

こんな方にはおすすめしません： ダッシュボード UI が必要な方、複数ユーザーでのアクセスが必要な方、または QuickBooks やスプレッドシートで十分な方。

始める前に必要なもの

• Node ≥ 24
• neonctl — npm install -g neonctl（無料の Neon アカウントが必要です。DB 用）
• MCP 対応ホスト： Claude Desktop、Claude.ai、Cursor、VS Code、または MCP の stdio／HTTP トランスポートに対応するホスト

クイックスタート（ローカル、stdio）

おすすめ — ソースからの完全自動セットアップ：

git clone https://github.com/yuens1002/bookie
cd bookie
npm install
npm run setup   # creates Neon DB, generates secrets, writes .env, runs db:push
npm run build

npm run setup を実行するとブラウザーが開き、Neon にログインできます。Neon を初めて利用する場合は、「アカウントを登録」リンクを使い、メールアドレスとパスワードではなく GitHub／Google／Microsoft を選んでください。同じブラウザーの往復で完了するため、待機中に CLI が中断される可能性があるメール認証の手間を避けられます。

npm run setup の最後に、Claude Desktop にそのまま貼り付けられる設定ブロックが表示されます：

{
  "mcpServers": {
    "bookie": {
      "command": "node",
      "args": ["/absolute/path/to/bookie/dist/index.js"],
      "env": {
        "BOOKIE_DB_URL": "<printed by setup>",
        "BOOKIE_DB_DIRECT_URL": "<printed by setup>",
        "BOOKIE_API_KEY": "<printed by setup>"
      }
    }
  }
}

同じ台帳を使う別のマシンを追加する場合 — クローンは不要です： stdio はローカルプロセスです。stdio MCP クライアントを実行する各マシンがそれぞれサーバーの独自コピーを起動するため、通常は各マシンに個別のチェックアウトが必要です。Neon DB のプロビジョニングが完了すれば（上記の npm run setup をいずれかのマシンで実行）、ほかのマシンでは同じ接続文字列を設定するだけで済みます。同期のための git clone、npm install、npm run build は不要です。そのマシンの MCP ホストから、代わりに公開済みパッケージを指定してください：

{
  "mcpServers": {
    "bookie": {
      "command": "npx",
      "args": ["-y", "bookie-mcp"],
      "env": {
        "BOOKIE_DB_URL": "<same value as your first machine>",
        "BOOKIE_DB_DIRECT_URL": "<same value as your first machine>",
        "BOOKIE_API_KEY": "<same value as your first machine>"
      }
    }
  }
}

npx は必要に応じて公開済みバージョンを取得して実行します。すべてのマシンで同じ BOOKIE_DB_URL を指定すれば、最初のマシン以外でチェックアウトを行わなくても、1 つの台帳を共有できます。

クローンせずに DB を初期化する場合： どのマシンからも接続文字列をまだ取得していない場合（たとえば npm run setup ではなく、Neon プロジェクトを手動で作成した場合）、bookie に同梱されているスキーマを直接適用してください：

mkdir bookie-mcp && cd bookie-mcp
npm install bookie-mcp
BOOKIE_DB_URL=<pooled> BOOKIE_DB_DIRECT_URL=<direct> npx prisma db push --schema=node_modules/bookie-mcp/prisma/schema.prisma

その後、上記と同じ npx -y bookie-mcp の設定を使用してください。

クイックスタート（リモート、HTTP — Claude.ai モバイル向け）

ワンクリックで Railway にデプロイできます：

Railway は事前ビルド済みのイメージを GHCR から取得するため、ソースのビルドは不要です。プロンプトが表示されたら、必要な環境変数を設定してください。詳しい手順（環境変数の一覧、Neon と Resend のセットアップ、Claude.ai OAuth コネクター）については、docs/DEPLOYING.md を参照してください。

UI がないのはなぜですか？

ホストの LLM はすでに CSV を読み取り、レシートの画像を認識し、文章を作成できます。Bookie が担うのは、LLM に即興で処理させるべきではないもの、つまり正確な複式簿記の台帳、整数のセント単位での金額計算、決定論的な分類ルール、再現可能なレポートです。モデルが言語と画像を処理し、サーバーが帳簿を管理します。

ツール

完全かつ常に最新のツールリファレンスは docs/TOOLS.md にあります（npm run docs:tools で再生成できます）。現在の内容：

ツール	機能
manage_accounts	アカウントの作成／一覧表示／アーカイブ（セグメント単位のカテゴリには税区分が設定されます）
add_transaction	複式簿記の仕訳を1件記録します（資金は → から → へ流れます）
split_transaction	1つの支払側とN個のカテゴリ側（複数カテゴリに分割された領収書）
import_transactions	銀行／カードのCSVを貸借が一致した仕訳としてインポートします — プレビュー → 確定、重複排除あり
manage_rules	自動分類ルールの作成／一覧表示／削除／テスト／提案を行います（カテゴリ分類 → アカウント／物件、または除外）。インポートプレビューの候補提示に使用されます。action=suggest は過去のカテゴリ分類をスキャンし、2回以上出現する摘要について候補ルールを返します
categorize_transaction	既存の仕訳の収入／費用側を再分類します — 明示的にアカウントを指定するか、保存済みルールを適用します
reconcile	銀行／カードの明細CSVを総勘定元帳と照合し、転記を消込済みとしてマークします — プレビュー後に確定
manage_receipts	領収書データを添付／一覧表示／削除するか、署名付きダウンロードURLを取得します。必要に応じて元ファイル（JPEG、PNG、WEBP、HEIC、またはPDF）をRailway Bucketストレージにアップロードできます
generate_report	月次照合サマリー、または会計年度のSchedule C／Schedule E税務損益計算書
export_report	任意のレポートをMarkdownまたはCSVとして出力します
send_report	レポートを実行し、Resend経由でメール送信します
query_transactions	日付範囲／アカウントで仕訳と転記を一覧表示します
account_balances	アカウントごとの現在残高

リソース

Bookieは、LLMがツールを呼び出さずに読み取れる2つのMCPリソースを公開します。

リソースURI	MIMEタイプ	内容
bookie://accounts	application/json	現在の残高を含むすべての有効なアカウント
bookie://reports/{year}	text/markdown	年間会計スナップショット：Schedule C、Schedule E、および月ごとに1行のサマリー（期首残高、純利益、消込済み転記数）

プロンプト

よくある簿記タスクをLLMが進めるための、あらかじめ用意されたワークフロープロンプトが3つあります。

プロンプト	パラメーター	目的
monthly-close	year、month	月末締めを段階的に進めます：CSVのインポート → カテゴリ分類 → 照合 → レポート →（任意で）メール送信
categorize-uncategorized	(なし)	収入／費用側が未分類の仕訳を見つけ、各仕訳のカテゴリ分類を進めます
prepare-tax-summary	year	Schedule C + Eを生成し、MarkdownおよびCSVとして出力して、必要に応じてメール送信します

設定

完全なリファレンスは .env.example を参照してください。主な変数：

変数	目的
BOOKIE_TRANSPORT	stdio（デフォルト）または http
BOOKIE_DB_URL	Neonのプール接続文字列
BOOKIE_DB_DIRECT_URL	Neonの直接接続文字列（db push 用）
BOOKIE_API_KEY	静的Bearerトークン（Claude Desktop／直接API）
PUBLIC_URL	デプロイ済みサーバーの公開HTTPSベースURL（Claude.aiコネクター）
JWT_SECRET	OAuth JWTアクセストークン用HS256署名シークレット
OAUTH_CLIENT_ID	OAuthクライアントID（デフォルト：claude-ai-connector）
OAUTH_CLIENT_SECRET	OAuthの使用時に必須：未設定の場合、/authorize はすべてのリクエストを拒否します（すべての訪問者が認可できないようにします）。/token でも検証されます。この値をClaude.aiコネクターの設定に入力してください。
RESEND_API_KEY	send_report 用のResend APIキー
RESEND_FROM	send_report 用の確認済み送信者アドレス（例：Bookie <[email protected]>）
AWS_ENDPOINT_URL / AWS_S3_BUCKET_NAME / AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGION	Railway Bucketの認証情報 — バケットをサービスに接続すると自動的に注入されます（AWS SDK Genericスタイルを使用）。manage_receipts での領収書ファイルのアップロードが可能になります

ドキュメント

• アーキテクチャ — データモデル、トランスポート、レイヤー構成
• デプロイ — Railway + Neon + Resend のセットアップ
• ロードマップ — 段階的な計画
• 変更履歴 — リリース内容
• リリース — バージョン管理とリリースプロセス
• ツール — 生成されたマニュアル
• コントリビューション — セットアップ、規約、テスト

安全性

Bookie は、Neon Postgres データベースに金融データを保存します。接続文字列は .env（gitignore 対象）と Railway の環境変数に保存し、決してコミットしないでください。HTTP トランスポートでは、すべての /mcp リクエストに認証が必要です。静的な Bearer トークン（BOOKIE_API_KEY）または /token エンドポイントが発行する OAuth JWT のいずれかを使用します。サーバーを localhost の外部に公開する前に、必ず少なくとも一方を設定してください。Claude.ai コネクターの OAuth 設定全体については、docs/DEPLOYING.md を参照してください。

ライセンス

MIT