Skip to main content
Glama
deenesjakoruzh
dht-net

household-account-book

by dht-net
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Headless Personal Accounting System for AI Agents

A headless personal accounting system designed specifically for AI agent consumption. It has no human-facing GUI; instead, all interactions are performed using the REST API or the Model Context Protocol (MCP) server stdio interface.

System Architecture

  • Language: Python 3.12+

  • Database: SQLite (single-file, local storage)

  • API Server: FastAPI (with automatic OpenAPI docs at /docs)

  • MCP Server: Python mcp SDK exposing tools over stdio transport

  • Deployment: Docker and Docker Compose

Related MCP server: accounting-mcp-server

Folder Structure

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

Getting Started (Native Setup)

1. Install Dependencies

Make sure Python 3.12+ is installed. Clone the repository and run:

# 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. Run the REST API Server

Start the FastAPI server on port 8900:

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

You can view the interactive API documentation at: http://localhost:8900/docs

3. Run the MCP Server

Run the MCP server locally over standard input/output (stdio):

python -m app.mcp_server

4. Run Unit Tests

To execute the test suite, run:

pytest

Deployment (Docker Setup)

You can build and deploy the application to a remote or local host using Docker and Docker Compose (tested on Ubuntu 24.04 LTS with Docker 29.x).

1. Start the Container

Start the container in detached mode. The SQLite database will be stored persistently inside the named volume accounting-data at /data/accounting.db inside the container.

docker compose up -d --build

2. Check Service Health

Ensure that the service is running and healthy:

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

# Show container status & health status
docker ps

Connecting AI Agents (MCP Configuration)

To allow LLM clients (like Claude Desktop) to interface directly with your accounting system, add the server to your client configuration file.

For Local Native Run

Add this to your Claude Desktop configuration file (typically at %APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on 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"
      }
    }
  }
}

For Docker Deployment

If the accounting server is running inside the Docker container, configure Claude Desktop to run commands inside the active container:

{
  "mcpServers": {
    "personal-accounting-docker": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "accounting-api",
        "python",
        "-m",
        "app.mcp_server"
      ]
    }
  }
}

API Usage Examples (curl Commands)

1. Create a New Account

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. List All Accounts

curl -X GET http://localhost:8900/accounts

3. Record an Expense (ID 1 represents Wallet Cash)

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. Record a Transfer (Move 2000 Yen from Savings Bank to Wallet Cash)

Assume Savings Bank ID is 2 and Wallet Cash ID is 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. Retrieve Aggregated Reports

Get a monthly report of your income, expenses, and category/account breakdown:

curl -X GET "http://localhost:8900/report?frequency=monthly"

6. Update a Transaction (Correct Mistakes)

Partial update — only the fields you provide are changed. Account balances are recalculated automatically:

# 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. Delete a Transaction (Undo a Mistake)

Deleting a transaction reverses its effect on the account balance (income is subtracted back, expense is added back):

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

8. Delete a Transfer

Deleting a transfer reverses the effect on both account balances:

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

9. Delete an Account

Deleting an account is refused (400) while it still has transactions or transfers referencing it. Remove those first, then delete:

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

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

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

  • 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

  • hledger-mcp

    eloircorona
    F
    license
    A
    quality
    B
    maintenance
    MCP server for hledger that exposes double-entry accounting tools to AI agents, enabling balance queries, transaction history, budget reports, and adding transactions to a journal.
    4
    -