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 mcp SDK, das Tools über stdio-Transport bereitstellt

• Bereitstellung: 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 manual

Erste 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 httpx

2. REST-API-Server ausführen

Starten Sie den FastAPI-Server auf Port 8900:

uvicorn app.main:app --host 0.0.0.0 --port 8900 --reload

Sie 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_server

4. Unit-Tests ausführen

Um die Testsuite auszuführen, führen Sie aus:

pytest

Bereitstellung (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 --build

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

Verbinden 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/accounts

3. 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/1

8. Überweisung löschen

Das Löschen einer Überweisung kehrt die Auswirkung auf beide Kontostände um:

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

9. 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/1