Skip to main content
Glama
deenesjakoruzh
dht-net

household-account-book

by dht-net
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

面向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

This server cannot be installed

F
license - not found
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

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.

  • mcp-beancount

    mekanics
    F
    license
    Not graded
    quality
    B
    maintenance
    A read-only MCP server that gives AI agents structured access to a Beancount personal finance ledger.
    1

  • 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

View all related MCP servers

Related MCP Connectors

  • Mini Accountant

    Hosted MCP server for Mini Accountant: invoices, expenses, customers, analytics, tax estimates.

  • XMemo

    Shared, governed long-term memory for AI agents across tools and sessions via MCP and REST.

  • Kody

    Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dht-net/household-account-book'

If you have feedback or need assistance with the MCP directory API, please join our Discord server