household-account-book
面向AI代理的无头个人记账系统
一个专为AI代理消费而设计的无头个人记账系统。它没有面向人类的图形界面;所有交互均通过REST API或模型上下文协议(MCP)服务器stdio接口完成。
系统架构
语言:Python 3.12+
数据库:SQLite(单文件、本地存储)
API服务器:FastAPI(在
/docs提供自动OpenAPI文档)MCP服务器:Python
mcpSDK,通过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 httpx2. 运行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_server4. 运行单元测试
要执行测试套件,请运行:
pytest部署(Docker设置)
您可以使用Docker和Docker Compose将应用程序构建并部署到远程或本地主机(已在Ubuntu 24.04 LTS和Docker 29.x上测试)。
1. 启动容器
以分离模式启动容器。SQLite数据库将持久存储在命名卷accounting-data中,位于容器内的/data/accounting.db。
docker compose up -d --build2. 检查服务健康状态
确保服务正在运行且健康:
# 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/accounts3. 记录一笔支出(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/18. 删除一笔转账
删除转账会逆转对两个账户余额的影响:
curl -X DELETE http://localhost:8900/transfers/19. 删除一个账户
当账户仍有交易或转账引用时,删除操作将被拒绝(400)。请先删除这些引用,然后再删除:
curl -X DELETE http://localhost:8900/accounts/1Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Headless API-first double-entry accounting & bookkeeping engine. 84 MCP tools over HTTP.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceDouble-entry accounting service for personal finance with MCP tools, enabling AI agents to manage accounts, transactions, budgets, and analytics via PostgreSQL.-
- -licenseNot gradedqualityNot gradedmaintenanceA 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.-
- AlicenseNot gradedqualityCmaintenanceDouble-entry accounting ledger MCP server for autonomous agents that enables creating accounts, posting journal entries, and generating financial reports.MIT
- FlicenseNot gradedqualityDmaintenanceMCP 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.-