billbook-mcp

# Billbook MCP 🌐 **Official Website: [billbook.top](https://billbook.top)** | Open-source Personal Accounting Desktop Application > **Billbook MCP** — AI-powered accounting tool based on Electron + Next.js 16, integrated with OpenClaw, Hermes Agent, and other clients via the standard MCP protocol, allowing one-line accounting, querying, and analysis. --- ## ✨ Features - 🤖 **AI-powered Accounting** — Integrated with OpenClaw / Hermes Agent and other MCP clients, one-line accounting: "Lunch 35 bucks" / "Coffee 18" - 📊 **Multi-object Tracking** — Separate accounting by person (self, partner, family), pets, projects, etc. - 🏷️ **Flexible Classification** — Customizable consumption categories + long-term apportionment (e.g., 60-day cat food, 30-day subscription service) - 🔍 **Intelligent Query** — "How much spent this month?" / "Average cat food cost in the last 30 days?" - 💾 **Local Data Storage** — All data stored locally in SQLite, no cloud processing - 📋 **Report Export** — One-click export of JSON / CSV format bills - 🔌 **Multi-MCP Client Compatibility** — Supports OpenClaw, Hermes Agent, Claude Desktop, Cursor, Continue.dev, etc. - 🇨🇳 **Native Chinese Support** — Fully Chinese interface, designed for personal/family accounting scenarios ## 🏗️ Project Architecture ``` billbook-mcp/ ├── desktop/ # Electron desktop application │ ├── main/ # Electron main process │ ├── mcp/ # MCP server │ │ └── billbook-server.mjs # Local MCP Server (21 tools) │ ├── state/ # Local SQLite database │ └── ledger-sqlite.js # Data layer (CRUD + snapshot synchronization) ├── docs/ # Documentation station (GitHub Pages) ├── scripts/ # Development auxiliary scripts ├── web/ # Official website (billbook.top) ├── AGENTS.md # MCP client access guide └── package.json ``` ## 🚀 Quick Start ### Desktop Application ```bash npm install npm run desktop:dev # Start Electron development environment npm run pack:win # Package Windows installation package ``` ### Using MCP Service (without desktop client) ```bash git clone https://github.com/Zachyucheng/billbook-mcp.git cd billbook-mcp npm install npm run setup:mcp ``` Then, add the configuration to your MCP client: ```yaml mcp_servers: billbook: command: node args: [desktop/mcp/billbook-server.mjs] cwd: /path/to/your/billbook-mcp ``` **OpenClaw** → Edit `openclaw.yaml`, add the above configuration. **Hermes Agent** → Edit `config.yaml`'s `mcp_servers` section. **Claude Desktop** → Configure in `claude_desktop_config.json`. **Cursor / Continue.dev** → Add to the corresponding MCP configuration file. > The database will be automatically created when the MCP server starts for the first time. See [MCP Configuration Guide](https://billbook.top/mcp-guide). ## 🤖 MCP Tool Overview Billbook MCP provides **21 tools**, covering the complete accounting process: | Category | Tool | Purpose | |:----|:----|:----| | 📝 Accounting | `create_transaction` `update_transaction` `delete_transaction` | Add, edit, delete transactions | | 🧑 Object Management | `create_object` `update_object` `list_ledgers` | Manage consumption objects | | 🏷️ Category Management | `create_category` `list_categories` | Manage consumption categories | | 🔍 Query | `search_transactions` `find_last_transaction` | Intelligent search | | 📊 Analysis | `summarize_category` `summarize_object` `compare_category_periods` `list_recurring_plans` | Periodic comparison and regular planning | | 📋 Export | `export_data` `export_report` | JSON/CSV export | | ⚙️ System | `get_database_status` `get_project_overview` `get_desktop_environment` `get_desktop_runtime_guide` `read_billbook_doc` | Status check and runtime self-inspection | ## 📖 Documentation - [MCP Access Guide](https://billbook.top/mcp-guide) — OpenClaw, Hermes Agent, Claude Desktop, etc. configuration details - [GitHub Pages Documentation Station](./docs/index.md) — Project introduction and getting started - [Desktop Roadmap](./docs/desktop-roadmap.md) — Feature planning - [Cloudflare Deployment](./docs/cloudflare-deployment.md) — Cloud deployment ## 📄 License Agreement **GNU Affero General Public License v3.0 (AGPL-3.0)** + Additional non-commercial use clause - ✅ Personal learning, research, non-commercial use - ❌ Strictly prohibited for any form of commercial use See [NOTICE.md](./NOTICE.md) and [LICENSE](./LICENSE). --- 🌐 [English Version](./README.en.md) > ℹ️ The project has been migrated from Billbook to **Billbook MCP**, with the name adjusted to improve GitHub searchability. > > Repository address: `git@github.com:Zachyucheng/billbook-mcp.git` (updated remote address) 📦 **International Logistics · DDP Freight Forwarder** — WeChat / Phone: v13025498279