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

---

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