Skip to main content
Glama
household-account-book

household-account-book

by dht-net

AIエージェント向けヘッドレス個人会計システム

AIエージェントによる利用を目的として設計されたヘッドレス個人会計システムです。人間向けのGUIはありません。代わりに、すべての操作はREST APIまたはModel Context Protocol (MCP)サーバーのstdioインターフェースを介して実行されます。

システムアーキテクチャ

  • 言語: Python 3.12+

  • データベース: SQLite(単一ファイル、ローカルストレージ)

  • APIサーバー: FastAPI(/docsで自動生成されるOpenAPIドキュメント付き)

  • MCPサーバー: Python mcp SDKが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 httpx

2. 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_server

4. ユニットテストの実行

テストスイートを実行するには、以下を実行します:

pytest

デプロイ(Dockerセットアップ)

DockerとDocker Composeを使用して、アプリケーションをリモートまたはローカルホストにビルドおよびデプロイできます(Ubuntu 24.04 LTS + Docker 29.xでテスト済み)。

1. コンテナの起動

デタッチモードでコンテナを起動します。SQLiteデータベースは、名前付きボリュームaccounting-data内のコンテナ内/data/accounting.dbに永続的に保存されます。

docker compose up -d --build

2. サービスヘルスチェック

サービスが実行中で正常であることを確認します:

# Verify REST API
curl http://localhost:8900/health

# Show container status & health status
docker ps

AIエージェントの接続(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/accounts

3. 支出の記録(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/1

8. 振替の削除

振替を削除すると、両方の口座残高への影響が逆転します:

curl -X DELETE http://localhost:8900/transfers/1

9. 口座の削除

口座を参照する取引または振替がまだ存在する場合、口座の削除は拒否されます(400)。先にそれらを削除してから、口座を削除します:

curl -X DELETE http://localhost:8900/accounts/1

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Double-entry accounting service for personal finance with MCP tools, enabling AI agents to manage accounts, transactions, budgets, and analytics via PostgreSQL.
      -
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A 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.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Double-entry accounting ledger MCP server for autonomous agents that enables creating accounts, posting journal entries, and generating financial reports.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      -