Skip to main content
Glama
deenesjakoruzh
dht-net

household-account-book

by dht-net
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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

This server cannot be installed

F
license - not found
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • Finance App

    youssefaltai
    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.

  • accounting-mcp-server

    mo7justin
    -
    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.

  • mcp-beancount

    mekanics
    F
    license
    Not graded
    quality
    B
    maintenance
    A read-only MCP server that gives AI agents structured access to a Beancount personal finance ledger.
    1

  • Agent Ledger

    nyx-builds
    A
    license
    Not graded
    quality
    A
    maintenance
    Double-entry accounting ledger MCP server for autonomous agents that enables creating accounts, posting journal entries, and generating financial reports.
    MIT

View all related MCP servers

Related MCP Connectors

  • Mini Accountant

    Hosted MCP server for Mini Accountant: invoices, expenses, customers, analytics, tax estimates.

  • XMemo

    Shared, governed long-term memory for AI agents across tools and sessions via MCP and REST.

  • Kody

    Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dht-net/household-account-book'

If you have feedback or need assistance with the MCP directory API, please join our Discord server