household-account-book
Headless persönliches Buchhaltungssystem für KI-Agenten
Ein headless persönliches Buchhaltungssystem, das speziell für die Nutzung durch KI-Agenten entwickelt wurde. Es hat keine benutzerorientierte GUI; stattdessen erfolgen alle Interaktionen über die REST-API oder die stdio-Schnittstelle des Model Context Protocol (MCP)-Servers.
Systemarchitektur
Sprache: Python 3.12+
Datenbank: SQLite (Einzeldatei, lokaler Speicher)
API-Server: FastAPI (mit automatischer OpenAPI-Dokumentation unter
/docs)MCP-Server: Python
mcpSDK, das Tools über stdio-Transport bereitstelltBereitstellung: Docker und Docker Compose
Related MCP server: accounting-mcp-server
Ordnerstruktur
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 manualErste Schritte (Native Einrichtung)
1. Abhängigkeiten installieren
Stellen Sie sicher, dass Python 3.12+ installiert ist. Klonen Sie das Repository und führen Sie aus:
# 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-Server ausführen
Starten Sie den FastAPI-Server auf Port 8900:
uvicorn app.main:app --host 0.0.0.0 --port 8900 --reloadSie können die interaktive API-Dokumentation unter http://localhost:8900/docs anzeigen.
3. MCP-Server ausführen
Führen Sie den MCP-Server lokal über Standardeingabe/-ausgabe (stdio) aus:
python -m app.mcp_server4. Unit-Tests ausführen
Um die Testsuite auszuführen, führen Sie aus:
pytestBereitstellung (Docker-Einrichtung)
Sie können die Anwendung mit Docker und Docker Compose auf einem entfernten oder lokalen Host erstellen und bereitstellen (getestet auf Ubuntu 24.04 LTS mit Docker 29.x).
1. Container starten
Starten Sie den Container im abgetrennten Modus. Die SQLite-Datenbank wird dauerhaft im benannten Volume accounting-data unter /data/accounting.db im Container gespeichert.
docker compose up -d --build2. Dienststatus überprüfen
Stellen Sie sicher, dass der Dienst läuft und fehlerfrei ist:
# Verify REST API
curl http://localhost:8900/health
# Show container status & health status
docker psVerbinden von KI-Agenten (MCP-Konfiguration)
Um LLM-Clients (wie Claude Desktop) die direkte Schnittstelle zu Ihrem Buchhaltungssystem zu ermöglichen, fügen Sie den Server zu Ihrer Client-Konfigurationsdatei hinzu.
Für lokale native Ausführung
Fügen Sie dies zu Ihrer Claude-Desktop-Konfigurationsdatei hinzu (normalerweise unter %APPDATA%\Claude\claude_desktop_config.json unter Windows oder ~/Library/Application Support/Claude/claude_desktop_config.json unter macOS):
{
"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"
}
}
}
}Für Docker-Bereitstellung
Wenn der Buchhaltungsserver im Docker-Container läuft, konfigurieren Sie Claude Desktop so, dass Befehle im aktiven Container ausgeführt werden:
{
"mcpServers": {
"personal-accounting-docker": {
"command": "docker",
"args": [
"exec",
"-i",
"accounting-api",
"python",
"-m",
"app.mcp_server"
]
}
}
}API-Nutzungsbeispiele (curl-Befehle)
1. Neues Konto erstellen
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. Alle Konten auflisten
curl -X GET http://localhost:8900/accounts3. Ausgabe erfassen (ID 1 steht für Bargeld in der Brieftasche)
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. Überweisung erfassen (2000 Yen von der Sparkasse auf Bargeld in der Brieftasche übertragen)
Angenommen, die ID der Sparkasse ist 2 und die ID von Bargeld in der Brieftasche ist 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. Aggregierte Berichte abrufen
Rufen Sie einen Monatsbericht über Ihre Einnahmen, Ausgaben und die Aufschlüsselung nach Kategorien/Konten ab:
curl -X GET "http://localhost:8900/report?frequency=monthly"6. Transaktion aktualisieren (Fehler korrigieren)
Teilaktualisierung – nur die von Ihnen angegebenen Felder werden geändert. Kontostände werden automatisch neu berechnet:
# 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. Transaktion löschen (Fehler rückgängig machen)
Das Löschen einer Transaktion kehrt ihre Auswirkung auf den Kontostand um (Einnahmen werden abgezogen, Ausgaben werden wieder hinzugefügt):
curl -X DELETE http://localhost:8900/transactions/18. Überweisung löschen
Das Löschen einer Überweisung kehrt die Auswirkung auf beide Kontostände um:
curl -X DELETE http://localhost:8900/transfers/19. Konto löschen
Das Löschen eines Kontos wird verweigert (400), solange noch Transaktionen oder Überweisungen darauf verweisen. Entfernen Sie diese zuerst und löschen Sie dann:
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.-