household-account-book
AIエージェント向けヘッドレス個人会計システム
AIエージェントによる利用を目的として設計されたヘッドレス個人会計システムです。人間向けのGUIはありません。代わりに、すべての操作はREST APIまたはModel Context Protocol (MCP)サーバーのstdioインターフェースを介して実行されます。
システムアーキテクチャ
言語: Python 3.12+
データベース: SQLite(単一ファイル、ローカルストレージ)
APIサーバー: FastAPI(
/docsで自動生成されるOpenAPIドキュメント付き)MCPサーバー: Python
mcpSDKがstdioトランスポート経由でツールを公開デプロイ: DockerおよびDocker Compose
Related MCP server: accounting-mcp-server
フォルダ構成
AI/
├── app/
│ ├── __init__.py
│ ├── db.py # SQLAlchemy SQLite connection & tables setup
│ ├── models.py # Pydantic schemas for data validation
│ ├── crud.py # Database operations (CRUD, reports, config)
│ ├── main.py # FastAPI API endpoints
│ └── mcp_server.py # MCP (Model Context Protocol) server configuration
├── tests/
│ ├── __init__.py
│ └── test_core.py # Complete Pytest unit tests suite
├── Dockerfile # Multi-stage optimized Docker file
├── docker-compose.yml # Docker compose configuration (Port 8900, volume mount)
├── .dockerignore
├── pyproject.toml # Poetry/Pip project dependencies
├── SCHEMA.md # Database schema reference for AI models
└── README.md # This manualはじめに(ネイティブセットアップ)
1. 依存関係のインストール
Python 3.12+がインストールされていることを確認してください。リポジトリをクローンして、以下を実行します:
# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install required packages
pip install fastapi uvicorn sqlalchemy pydantic mcp
# Install development packages for tests
pip install pytest httpx2. REST APIサーバーの起動
ポート8900でFastAPIサーバーを起動します:
uvicorn app.main:app --host 0.0.0.0 --port 8900 --reload対話型APIドキュメントは次の場所で確認できます:http://localhost:8900/docs
3. MCPサーバーの起動
標準入出力(stdio)経由でMCPサーバーをローカルで実行します:
python -m app.mcp_server4. ユニットテストの実行
テストスイートを実行するには、以下を実行します:
pytestデプロイ(Dockerセットアップ)
DockerとDocker Composeを使用して、アプリケーションをリモートまたはローカルホストにビルドおよびデプロイできます(Ubuntu 24.04 LTS + Docker 29.xでテスト済み)。
1. コンテナの起動
デタッチモードでコンテナを起動します。SQLiteデータベースは、名前付きボリュームaccounting-data内のコンテナ内/data/accounting.dbに永続的に保存されます。
docker compose up -d --build2. サービスヘルスチェック
サービスが実行中で正常であることを確認します:
# Verify REST API
curl http://localhost:8900/health
# Show container status & health status
docker psAIエージェントの接続(MCP設定)
LLMクライアント(Claude Desktopなど)が会計システムに直接接続できるようにするには、サーバーをクライアント設定ファイルに追加します。
ローカルネイティブ実行の場合
これをClaude Desktopの設定ファイルに追加します(通常はWindowsでは%APPDATA%\Claude\claude_desktop_config.json、macOSでは~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"personal-accounting": {
"command": "/path/to/your/venv/bin/python",
"args": ["-m", "app.mcp_server"],
"cwd": "/path/to/your/project/directory",
"env": {
"DATABASE_URL": "sqlite:////path/to/your/project/directory/accounting.db"
}
}
}
}Dockerデプロイの場合
会計サーバーがDockerコンテナ内で実行されている場合は、アクティブなコンテナ内でコマンドを実行するようにClaude Desktopを設定します:
{
"mcpServers": {
"personal-accounting-docker": {
"command": "docker",
"args": [
"exec",
"-i",
"accounting-api",
"python",
"-m",
"app.mcp_server"
]
}
}
}API使用例(curlコマンド)
1. 新しい口座の作成
curl -X POST http://localhost:8900/accounts \
-H "Content-Type: application/json" \
-d '{"name": "Wallet Cash", "type": "cash", "balance": 5000}'curl -X POST http://localhost:8900/accounts \
-H "Content-Type: application/json" \
-d '{"name": "Savings Bank", "type": "bank", "balance": 150000}'2. 全口座の一覧表示
curl -X GET http://localhost:8900/accounts3. 支出の記録(ID 1は財布の現金を表します)
curl -X POST http://localhost:8900/transactions \
-H "Content-Type: application/json" \
-d '{
"date": "2026-08-02",
"amount": 850,
"type": "expense",
"category": "Food",
"description": "Lunch at restaurant",
"account_id": 1,
"tags": ["lunch", "outing"]
}'4. 振替の記録(普通預金から財布の現金へ2000円を移動)
Savings BankのIDが2、Wallet CashのIDが1であると仮定します。
curl -X POST http://localhost:8900/transfers \
-H "Content-Type: application/json" \
-d '{
"date": "2026-08-02",
"amount": 2000,
"from_account_id": 2,
"to_account_id": 1,
"description": "ATM withdrawal to wallet"
}'5. 集計レポートの取得
収入、支出、およびカテゴリ/口座別の内訳の月次レポートを取得します:
curl -X GET "http://localhost:8900/report?frequency=monthly"6. 取引の更新(誤りの修正)
部分更新 — 指定したフィールドのみが変更されます。口座残高は自動的に再計算されます:
# Change the amount of transaction ID 1 from 850 to 950
curl -X PUT http://localhost:8900/transactions/1 \
-H "Content-Type: application/json" \
-d '{"amount": 950}'7. 取引の削除(誤りの取り消し)
取引を削除すると、口座残高への影響が逆転します(収入は差し引かれ、支出は加算されます):
curl -X DELETE http://localhost:8900/transactions/18. 振替の削除
振替を削除すると、両方の口座残高への影響が逆転します:
curl -X DELETE http://localhost:8900/transfers/19. 口座の削除
口座を参照する取引または振替がまだ存在する場合、口座の削除は拒否されます(400)。先にそれらを削除してから、口座を削除します:
curl -X DELETE http://localhost:8900/accounts/1Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Headless API-first double-entry accounting & bookkeeping engine. 84 MCP tools over HTTP.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceDouble-entry accounting service for personal finance with MCP tools, enabling AI agents to manage accounts, transactions, budgets, and analytics via PostgreSQL.-
- -licenseNot gradedqualityNot gradedmaintenanceA personal accounting MCP server that enables AI assistants to record and query financial transactions through natural language, supporting income/expense tracking, balance inquiry, and monthly summaries.-
- AlicenseNot gradedqualityCmaintenanceDouble-entry accounting ledger MCP server for autonomous agents that enables creating accounts, posting journal entries, and generating financial reports.MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for Firecent, a personal finance app, enabling AI agents to read and manage financial data through REST API, including accounts, records, categories, and queries.-