Skip to main content
Glama
household-account-book

household-account-book

by dht-net

面向AI代理的无头个人记账系统

一个专为AI代理消费而设计的无头个人记账系统。它没有面向人类的图形界面;所有交互均通过REST API或模型上下文协议(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日元从储蓄银行转到钱包现金)

假设储蓄银行的ID为2,钱包现金的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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • 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.
      -
    • -
      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.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Double-entry accounting ledger MCP server for autonomous agents that enables creating accounts, posting journal entries, and generating financial reports.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      -