gnucash mcp
与法学硕士合作的免费开源会计软件。
通过Claude（或任何人工智能助手）与您的GnuCash书籍交谈 支持MCP）。问“我这个月过得怎么样”，口述 把你的交易大声说出来，把账簿交给人工智能 当你专注于经营你的生活或事业时，要跟上。
您的数据保留在您的机器上。您的审核日志将保留在您的 机器。没有任何东西上传到任何地方——人工智能读写 您的本地GnuCash文件，仅此而已。
此仓库中有两本真实的、填充的样本书，因此您可以 在做出任何决定之前先试试。它们很现实，很满 多年的活动，混合货币，客户，发票， 预算，工作。五分钟内穿过一个；如果它 点击，将服务器指向你自己的书，你就完成了。
______________________________________________________________________
它看起来像什么？
这是你的AI助手打开其中一个时看到的 示例书籍——一次通话中的完整财务仪表板：
Book: samples/alex-chen-morales.gnucash
Currency: USD
Data range: 2025-01-01 to 2026-05-31
Last entry: 2026-05-31 (future-dated, 31 days ahead)
Warnings:
⚠ Past due invoice: Berlin Digital GmbH 58 days past 30-day default, EUR 4,200 (no term set)
⚠ Stale price: GBP last updated 150 days ago
Accounts: 108 total
Assets: 12 accounts, USD 602680.49
Condo: USD 473250.00
VTSAX: 230.7620 VTSAX @ 170.99 (USD 39457.99)
Vehicle: USD 27845.00
401k: USD 13404.62
Checking Account: USD 12393.11
...
Liabilities: 4 accounts, USD 418457.79
Credit cards (2): USD 38044.26
Loans (2): USD 380413.53
Top 3: Mortgage USD 372199.55, Chase Sapphire USD 22383.23, Business Amex USD 15661.03
Receivables: 3 accounts, USD 10246.46
Accounts Receivable EUR: USD 4908.96
Accounts Receivable: USD 3500.00
Accounts Receivable CAD: USD 1837.50
Reconciliation:
Checking Account: 174 splits unreconciled since 2025-12-30 (4 months behind) ⚠
7 accounts never reconciled ⚠
Net worth trajectory:
12mo ago: USD 187,925
6mo ago: USD 180,614
3mo ago: USD 191,350
1mo ago: USD 185,444
now: USD 184,223
Monthly net (last 6 months):
Apr 2026 (MTD): -9,056
Mar 2026: +3,092
Feb 2026: +5,202
Jan 2026: +1,086
Dec 2025: +4,853
Nov 2025: -1,494
Runway: 121 days (USD 84,579 liquid / USD 694/day burn)
Budget (2026 Annual Budget): 41% used / 33% elapsed (+8% over pace)
Transactions: 2473
Scheduled: 13 recurring, none due in next 7 days
Business: 4 customers, 2 vendors, 1 employee这不是屏幕截图，这是人工智能的实际方向 视图。净值轨迹、跑道、预算节奏、谁欠你 钱，过期的，还没对账的。一个电话， 你的助手甚至在你还没来得及之前就已经了解了全貌 说完了打招呼。
______________________________________________________________________
这是给谁的？
- 个人理财人员 他们把书放在GnuCash里
想口述交易，问他们的助理在哪里 资金正在流动，寻求和解帮助，计划预算。
- 小企业主 他们在GnuCash和
想要开具发票、跟踪应收账款、查看供应商 在不离开谈话的情况下，管理现金流。
- 关心他们的数据保持本地的人。 没有云
同步。没有SaaS。你的 .gnucash 档案是记录系统； 这只是给你的人工智能一种读写方式 GnuCash本身就是这样。
你不需要成为一名开发人员。您需要：
- 计算机（Mac、Windows或Linux）
- GnuCash本身，或愿意安装它（免费
- 支持MCP的AI助手（Claude Desktop是
最常见；Claude Code、Continue.dev和其他人也在工作）
- 运行样书需要10分钟，然后再运行10分钟
指向你自己的
______________________________________________________________________
尝试一下，不要冒任何风险
回购提供了两本样本书——完全填充的合成书 你可以在不接触真实数据的情况下与账簿交谈。挑选 首先，将服务器指向它，然后开始提问。
samples/alex-chen-morales.gnucash --个人+自由职业者
一家总部位于西雅图的独立软件承包商，拥有一家美国有限责任公司。 美元违约。2025年，约141个账户，约2475笔交易 2026.拥有抵押贷款，与VTSAX/VBTLX/AAPL/MSFT/ETH有经纪关系 控股，401（k），四个客户，涵盖美元/欧元/英镑/加元 外币发票、预定账单、预算——很漂亮 服务器可以做的一切，都在一本书中。
samples/lin-wei.gnucash --跨境小企业
一位深圳的小企业主经营着一家跨境企业 电子商务运营。人民币违约。~105个账户，~1960个 交易。以人民币、美元/欧元支付的中国客户 以外币支付并实现外汇损益的客户 on rate moves, domestic Chinese investments (茅台, 宁德时代, ETF）、基于LPR的抵押贷款、混合支付轨道（支票+ 支付宝+微信支付）。
这两本书都是虚构的。看 示例/README.md 了解每种产品的完整分类。
______________________________________________________________________
快速入门（5分钟）
1.安装
git clone https://github.com/ninetails-io/gnucash-mcp.git
cd gnucash-mcp然后：
uv sync # if you have uv (recommended)
# or
pip install -e . # if you have pip如果你没有uv，用一条线安装：curl -LsSf https://astral.sh/uv/install.sh | sh
2.制作一本样书的工作副本
服务器将审计日志和自动备份与 书籍档案。你不想让他们中的任何一个回到 repo，所以先把书复制到repo之外的某个地方：
mkdir -p ~/gnucash-mcp-scratch
cp samples/alex-chen-morales.gnucash ~/gnucash-mcp-scratch/alex.gnucash3.向Claude Desktop介绍服务器
查找您的Claude桌面配置：
- 雨衣：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json
添加以下内容（用实际路径替换这两条路径）：
{
"mcpServers": {
"gnucash": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/gnucash-mcp",
"python",
"-m",
"gnucash_mcp",
"--modules=all"
],
"env": {
"GNUCASH_BOOK_PATH": "/Users/yourname/gnucash-mcp-scratch/alex.gnucash"
}
}
}
}完全退出Claude Desktop（而不仅仅是关闭窗口-- 退出）并重新打开。寻找锤子🔨 图标旁边 文本输入。这意味着服务器已连接。
4.试试看
问克劳德：
- “总结一下这本书。”
- “我的净资产在做什么？”
- “让我看看谁欠我钱。”
- “上个月我吃饭花了多少钱？”
- “设定每月500美元的杂货预算。”
第一个响应通常从仪表板开始 上面。之后的一切都是对话。
当你准备指向自己的书时，替换 GNUCASH_BOOK_PATH 价值与通往真实的道路 .gnucash 文件（下一步将详细介绍），重新启动Claude Desktop，然后离开。
______________________________________________________________________
连接到自己的书
一次性转换：GnuCash文件格式
服务器只读取 SQLite GnuCash文件的形式，而不是 旧的XML表单。要转换：
- 在GnuCash中打开你的书
- File → 另存为
- 将“数据格式”更改为 SQLite3
- 使用新文件名保存（例如。
mybook-sqlite.gnucash) - 保留XML原件作为备份。
你只做一次。从那时起，GnuCash和MCP服务器 两者都针对相同的SQLite文件。
设置路径
更新 GNUCASH_BOOK_PATH 在您的Claude Desktop配置中 指向您自己的SQLite格式书籍。重新启动克劳德桌面。
使用绝对路径，不~或相对路径。开 Mac/Linux：/Users/yourname/Documents/mybook.gnucash.On 窗户：C:\\Users\\yourname\\Documents\\mybook.gnucash（注意双反斜杠——这是JSON的要求）。
其他AI客户端
这是一个 主控程序 服务器，所以 它适用于任何使用MCP的客户端。非克劳德注意事项 桌面客户端：
- 克劳德代码:
claude mcp add-json gnucash '{"command":"uv","args":["run","--directory","/path/to/gnucash-mcp","python","-m","gnucash_mcp","--modules=all"],"env":{"GNUCASH_BOOK_PATH":"/path/to/your/book.gnucash"}}'
添加 --scope user 对于所有项目， --scope project 为了 只有这一个。
- 还有别的吗：set
GNUCASH_BOOK_PATH然后跑
uv run gnucash-mcp （或 gnucash-mcp 如果通过pip安装）。
______________________________________________________________________
你可以要求它做什么
一次非详尽的旅行。自然地说出其中任何一句话—— 助理翻译。
录制活动
“我今天在Safeway花了47.50美元买杂货，用我的 签证。" 记录：47.50美元来自信用卡：Visa 费用：2026年4月30日的杂货。描述：“安全通道”。
设置经常性账单
“将我的租金设置为经常性账单。1月1日1850美元 每月检查。" 已创建计划交易“月租”：1850美元 每月，从资产：检查到费用：租金。下次到期日： 2026年5月1日。
投资跟踪
“我在401（k）中以每股170.99美元的价格购买了1000美元的VTSAX。” 有记录的VTSAX收购：5.85股，每股170.99美元。成本 基础：1000.00美元。为跟踪资本收益而创建的地块 当你最终卖出。
向客户开具发票
“创建一个名为Acme Corp的客户，并向他们开具1500美元的发票 咨询。" 创建了客户Acme Corp（id 000005）和发票000019： 1×咨询费用为1500.00美元=1500.00美元。打开。告诉我什么时候 你已经准备好发布了。
外币发票
“第一季度预付款柏林数字发票4200欧元，30天后到期。” 为Berlin Digital GmbH创建了000020欧元发票： 1×第一季度留存额为4200欧元=4200欧元。净30。当他们 支付后，我将把已实现的汇率损益记入您的账户 自动开设外汇账户。
提出问题
“今年我在每个供应商身上花了多少钱？” 办公室仓库：2340美元（4张账单，0美元未付） CloudHost公司：1200美元（2张账单，600美元未付） 法律助理：3500美元（1张账单，3500美元未付） 账单总额7040美元/已支付2940美元/未付4100美元。
和解
“帮我核对一下四月的声明。” \[带你走过去：拉着无法调和的裂痕，问你 要确认已清算的交易，请计算运行 平衡，标记匹配的匹配，留下 不匹配的情况需要你调查。\]
______________________________________________________________________
隐私和安全
您的数据不会离开您的机器。 此服务器是 读写本地文件的本地进程。人工智能 与您交谈的助理（Claude Desktop等）看到 工具调用的结果——与您在上面看到的内容相同 屏幕——但文件本身保持不变。
每次写入都会被记录下来。 人类可读的审计追踪仍然存在 在您的图书档案旁边 .gnucash.mcp/audit/, 每天一个日志文件。您可以随时阅读以查看 确切地说，什么时候发生了变化。样本输入：
2026-04-30 14:32 POST INVOICE id:000019
total: 1500.00 date: 2026-04-30
account: Assets:Accounts Receivable txn:a1b2c3d4自动备份。 在每封信的第一封信之前 会话，服务器将您的书快照到 .gnucash.mcp/backups/ --所以，如果事情进展顺利 错了，你可以回滚到已知的良好状态，而无需 依靠时间机器或你自己的习惯。备份是 已验证 PRAGMA integrity_check 在宣布之前 有效。看 docs/RESTORE_ROM_BACKUP.md 用于回滚过程。
协调的分割受到保护。 服务器拒绝 在没有明确说明的情况下删除或修改已对账的拆分 覆盖，因此粗心的提示不会悄悄地使您的 最后一次银行对账。
作废≠删除。 当你告诉人工智能“取消这个 交易，”它使用GnuCash的适当会计无效-- 为审计跟踪保留交易价值 归零。删除是破坏性的选择；AI会告诉 你知道它在做什么。
免责声明： 该软件按“原样”提供 MIT许可证，没有任何形式的保证。这 作者不对任何数据丢失、损坏或 因使用而产生的财务差异。你只是 负责维护自己的备份和验证 你的书的准确性。
______________________________________________________________________
限制AI可以看到的内容
默认情况下，服务器会公开其完整的工具集（87个工具 v1.2.1版本）。每个工具的描述都存在于AI的系统中 提示，这会在每条消息上消耗上下文。如果你只使用 一些功能——比如，没有投资，也没有业务模块-- 您可以告诉服务器只加载这些模块：
"args": [
"run", "--directory", "/path/to/gnucash-mcp",
"python", "-m", "gnucash_mcp",
"--modules=core,reporting,budgets,scheduling"
]| 模块 | 它给你什么 |
|---|---|
core | 账户、交易、仪表板。始终装载。 |
reconciliation | 银行对账，无效/未作废 |
reporting | 支出、收入、资产负债表、净值、现金流、债务偿还 |
budgets | 创建预算、设定目标、跟踪差异 |
scheduling | 经常性交易、即将到来的账单 |
investments | 股票、共同基金、手数、资本收益跟踪 |
business | 客户、供应商、员工、发票、账单、付款 |
admin | 账户级元数据（APR、信用额度等） |
backup | 手动快照工具 |
使用 --modules=all 加载所有内容（默认为 上面的示例书快速入门），或列出一个子集来保存您的 背景光。您还可以设置 GNUCASH_MCP_MODULES=core,reporting 作为一种环境 变量代替。
______________________________________________________________________
v1.2.1中有什么
此版本是v1.2业务的长尾完成- 模块承诺——v1.2在首次发布时应该是什么， 再加上对每一笔非美元违约的慷慨纠正 试卷浮出水面的路径。
专业：
- 多币种，端到端。 外币发票
根据您的汇率进行邮寄和支付 价格表；发布日期和支付日期之间的利率漂移为 在专用收入中确认为已实现的外汇损益 帐户（或您指定的帐户）。
- 一个完整的首次通话控制面板。
get_book_summary现在
显示净值轨迹、跑道、每月净收入， 预算调整、对账积压和拆分计数， 即将到来的法案和警告——扭转法学硕士的第一个电话 从“书籍的现状”到“我需要什么” 做下一步。"
- 客户/供应商/员工CRUD完成。 创建，
列表、获取、更新（1.2.1中的新功能）和删除。不再 需要打开GnuCash本身来修复一个拼写错误 地址。
- 发布工作流生命周期完成。
post_invoice和
pay_invoice 由...连接 unpost_invoice （新）如此张贴 发票可以在不进行SQL操作的情况下彻底撤销。 delete_transaction 拒绝通过以下方式打破生命周期 直接删除过账记录。
- 自动备份。 首次写入每个会话快照
书；分阶段保留（7节课/4周/6 每月）让你在不填满磁盘的情况下得到保护。
再加上一千个较小的修复 从密集测试开始 两本真实的书——多币种报告、债务偿还 抵押贷款摊销、无效付款处理、员工- 费用凭证挂钩等等。看 规格/NET_STEPS_1_3.md 对于1.3 路线图（税务表、工作、信用票据、员工费用 代金券）。
主要版本的精简更新日志位于 更改日志.md.
______________________________________________________________________
故障排除
不🔨 锤子图标，或“找不到工具”
- 完全退出Claude Desktop，然后重新打开它。（关闭
窗口是不够的，您必须退出应用程序。)
- 验证配置中的路径是否绝对正确。
- 检查JSON中的尾随逗号——它们会破坏配置
默默地。
“找不到书”
- 使用绝对路径，而不是
~或相对路径。 - Mac/Linux：
/Users/yourname/Documents/book.gnucash - 窗户：
C:\\Users\\yourname\\Documents\\book.gnucash
（双反斜杠——JSON要求）
“无法打开书本”/peicash错误
- 确认你的书在 SQLite 格式，而不是XML。
- 确保GnuCash不是用同一本书打开的——文件锁。
- 尝试在GnuCash中打开这本书，以验证它不是
腐败。
“未找到帐户”
- 使用完整帐户路径：
Expenses:Groceries，不仅
Groceries.
- 或者让助理列出账户：“列出我的账户。”
出错了
- 打开审计日志
.gnucash.mcp/audit/—
自服务器首次运行以来的每次写入都有 细节之前/之后。
- 如果你需要回滚， docs/RESTORE_ROM_BACKUP.md
走过它。
______________________________________________________________________
支持项目
如果gnucash mcp对您有用，请考虑 给我买杯咖啡。这有帮助 继续发展。
______________________________________________________________________
面向开发者
贡献者指南和设计说明已发布 CLAUDE.md.快速定位：
uv sync --extra dev
uv run pytest # 1,044 tests as of v1.2.1
uv run ruff check src/ tests/
uv run black --check src/ tests/服务器构建在 皮尔卡什 python GnuCash SQLite书籍的接口）和 MCP Python SDK. 大约18000行Python源代码，20000行测试， 模块化，因此禁用的模块在运行时不需要任何成本。
许可证
致谢
- GnuCash --免费、开源
该服务器提供的会计软件可以进行对话。
- 皮尔卡什 python
GnuCash SQLite书籍的接口。
模型上下文协议实现。