mcpField
G
gnucash-mcp

gnucash-mcp

本地服务
github.com/ninetails-io金融数据843 周前更新
代码仓库

关于 gnucash-mcp

gnucash-mcp 是一个面向 GnuCash 账本的 MCP 服务，让 AI 助手直接读取和写入本地的 .gnucash 文件。它适合个人理财用户和小型企业主，服务运行在本机，账本数据和审计日志不会离开用户的机器。

主要功能

  1. 01本地读取和写入 GnuCash 账本
  2. 02一次调用返回账本概览与财务仪表盘
  3. 03提供按模块划分的工具集合
  4. 04支持 SQLite 文件与 PostgreSQL、MySQL 数据库
  5. 05内置三套虚构的示例账本

适用场景

  1. 01用自然语言记录和查询交易
  2. 02查看余额、预算进度与应收账款
  3. 03在对话中完成账目对账
  4. 04通过 AI 助手管理客户发票与供应商账单

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库
安装包
mcpbgnucash-mcp-1.5.0.mcpb

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

gnucash-mcp

与大模型协同工作的免费开源会计软件。

通过 Claude（或任何支持 MCP 的 AI 助手）与您的 GnuCash 账簿对话。询问“我这个月的财务状况怎么样”，直接口述交易记录，让 AI 接手账簿维护，您则专注于经营生活或业务。

服务在您的设备上运行，并操作本地 GnuCash 文件；文件及其审计日志绝不会离开本地。您的 AI 助手可以看到工具调用返回的内容（余额、收款人、发票），就像您在屏幕上看到的一样。

从 1.4 升级？ 首次使用 1.5 写入数据前，请阅读升级指南。

一键安装： 在 Claude Desktop 上，下载最新版本中的 .mcpb 安装包，双击即可运行——无需终端，也无需配置文件。其他所有 MCP 客户端——ChatGPT/Codex、Gemini、Antigravity 等——都只需几行设置即可连接。无论使用哪种方式，您已经付费的 AI 订阅都能变成一位永远不会寄账单的记账员。

三本逼真的示例账簿可让您在提交任何数据前先行试用：包含全年活动记录、多种货币、客户、发票和预算。Claude Desktop 安装包中已包含这些账簿；从克隆的仓库开始，只需一条命令即可生成。花五分钟体验其中一本；如果觉得合适，将服务指向您自己的账簿即可。

看起来是什么样？

当您的 AI 助手打开一本示例账簿时，它看到的就是这样——一次调用即可获得完整的财务概览：

Book: alex-chen-morales.gnucash
Currency: USD
Data range: 2025-01-01 to 2026-10-08
Last entry: 2026-10-08 (today)
Chart of accounts: 111 total (109 active) — drill into any branch with list_accounts(root="Assets:Investments"):
  Assets (25 total): Investments (9), Current Assets (5), Fixed Assets (3), Receivables (3), Retirement (3)
  Liabilities (8 total): Credit Card (3), Loans (3)
  Equity (3 total)
  Income (11 total): Investment Income (6)
  Expenses (64 total): Business (14), Taxes (10), Utilities (6), Auto (4), Housing (4), Interest (4), Insurance (3), Pet (3)
Assets: USD 874270.54
  Condo: USD 475000.00
  VTSAX: 453.4039 VTSAX @ 185.53 (USD 84120.03)
  UWRP 403(b): USD 74778.40
  Savings Account: USD 60000.00
  Cascade Code LLC Checking: USD 41390.64
  ...
Liabilities: USD 389695.79
  Credit cards (2): USD 1319.99
  Loans & other (2): USD 385873.30
  Top 3: Mortgage USD 373846.80, Auto Loan USD 12026.50, Chase Sapphire USD 876.31
Receivables: 2 accounts, USD 27324.47 (4 invoices, 0 overdue; included in Assets total)
  Accounts Receivable: USD 22425.00
  Accounts Receivable EUR: USD 4899.47
Payables: 1 account, USD 2502.50 (1 bill, 0 overdue; included in Liabilities total)
  Accounts Payable: USD 2502.50
Jobs: 3 active
Frequently used accounts (last 180 days — any account parameter accepts the %guid or the full name; a %guid is fewer tokens and faster to write):
  %528b7d9	Assets:Current Assets:Checking Account [BANK]
  %8799a0a	Liabilities:Credit Card:Chase Sapphire [CREDIT]
  %839fcf8	Expenses:Dining
  ...
Reconciliation:
  6 accounts current
Net worth trajectory:
  12mo ago: USD 345,969
   6mo ago: USD 381,961
   3mo ago: USD 429,392
   1mo ago: USD 443,546
       now: USD 484,575
Monthly net (income - expenses, last 6 months):
  Oct 2026 (MTD): +11,955 (vs Sep 1-8: -2,365)
  Sep 2026: +25,894
  Aug 2026: +7,588
  Jul 2026: +10,307
  Jun 2026: +24,092
  May 2026: +9,017
Runway: 579 days (USD 246,844 liquid / USD 426/day cash out incl. debt paydown, 180-day avg; cards owe USD 1,320)
Budget (2026 Annual Budget): USD 27,736 spent / USD 28,683 expected by today (-3%)
Transactions: 2227
Scheduled: 20 recurring, 16 due in next 7 days (USD 15,128 out)
Business: 8 customers, 3 vendors
Budgets: 2
Commodities: AAPL, CAD, ETH, EUR, MSFT, USD, VBTLX, VTSAX

这不是截图——而是 AI 实际看到的概览。净资产变化趋势、资金可维持时间、预算进度、谁欠您钱、哪些款项逾期、哪些账目尚未对账。一条调用，就能让您的助手在您打完招呼之前掌握全貌。

适合哪些人？

  • 个人理财用户：使用 GnuCash 记账，希望口述交易、询问助手钱都花到哪里去了、获得对账帮助并规划预算。
  • 小型企业主：使用 GnuCash 记账，希望开具发票、跟踪应收款、查看供应商支出、管理现金流，同时无需离开对话。
  • 在意数据保留在本地的人：没有云同步，没有 SaaS。您的 .gnucash 文件是记录系统；本项目只是让 AI 能够像 GnuCash 本身那样读取和写入数据。

您无需是开发者，只需要：

  • 一台电脑（Mac、Windows 或 Linux）
  • GnuCash，或愿意安装它（可从 gnucash.org 免费获取）
  • 一个支持 MCP 的 AI 助手（最常见的是 Claude Desktop；Claude Code、Continue.dev 等也可使用）
  • 花 10 分钟运行示例账簿，再花 10 分钟将服务指向您自己的账簿

无风险试用

此仓库提供三种示例人物设定——合成账簿，您可以与之对话，而无需触碰自己的真实数据。安装包中已包含完整构建的账簿；从克隆的仓库开始，只需一条命令即可生成。选一本账簿，将服务指向它，然后开始提问。

samples/alex-chen-morales.gnucash — 个人财务 + 自由职业

这是一位居住在西雅图的独立软件承包商，拥有一家单一成员有限责任公司，配偶则在医院受雇。默认货币为 USD。账簿包含 111 个账户，以及从 2025 年至生成日期的 2,000 多笔交易。涵盖房贷、持有 VTSAX/VBTLX/AAPL/MSFT/ETH 的证券账户、与配偶的 403(b) 并列的个人 Solo 401(k)、以 USD、EUR 和 CAD 开具发票的 8 位客户、通过应付账款（A/P）结算的分包商、华盛顿州 B&O 税、定期账单、预算——基本囊括了此服务能做的一切。

samples/lin-wei.gnucash — 深圳软件工作室

一位深圳开发者经营着一家已注册的个人独资工作室，开发跨境电商软件；其配偶在医院领工资。默认使用 CNY，采用原生 zh_CN 科目表。101 个科目和约 3,000 笔交易。深圳科技客户（Tencent、DJI、SF Tech 等）以 CNY 付款；USD/EUR 客户以外币付款，并因汇率变动产生已实现汇兑损益；投资于中国境内的资产（宁德时代和两只 ETF）；有一名兼职员工、一张 HKD 信用卡、一笔房贷，以及混合支付渠道（公司账户 + Alipay + WeChat Pay）。

samples/sabine-brenner.gnucash — 德国自由职业者，SKR03 科目表

一位常驻慕尼黑的自由职业设计师。默认使用 EUR，采用德国 SKR03 会计科目表——每个科目名称均为德语。125 个科目和约 1,900 笔交易，包含实时增值税申报和按 1% 规则计税的公司用车。如果某项功能假定科目名称为英文或货币为 USD，那么 Sabine 的账簿就能暴露问题。

三本账簿均为虚构。各账簿内容的完整说明请参见 samples/README.md。

快速开始

一键安装（Claude Desktop）

从最新版本下载 .mcpb bundle，然后双击。Claude Desktop 会安装 MCP 服务——无需终端、配置文件或 Python。安装程序会询问三项内容：

  • 你的 GnuCash 账簿——通过文件选择器选择。账簿必须采用 SQLite 格式；如果你的账簿仍是较旧的 XML 格式，请先完成一次性转换。选择多本账簿，即可在聊天中切换使用。
  • 演示账簿——勾选一个复选框即可启用上述三本样例账簿，让你先用虚构数据进行探索，再决定是否连接自己的账簿。
  • “你会向客户开具发票吗？”——选择“是”会启用业务套件（客户发票、供应商账单、员工费用）。其他功能——预算、计划交易、投资跟踪——始终启用。

安装就这么简单。

试试看

向 Claude 提问：

  • “总结一下账簿。”
  • “我的净资产最近有什么变化？”
  • “列出欠我钱的人。”
  • “上个月我在餐饮上花了多少钱？”
  • “设置每月 500 美元的杂货预算。”

首次回复通常会从上文提到的仪表板开始。之后的一切都可以通过对话完成。

准备好使用自己的账簿时，请参阅下文的连接自己的账簿。

其他 AI 客户端，或从源代码安装

ChatGPT 和 Codex、Claude Code、Gemini CLI、Google Antigravity，以及其他任何 MCP 客户端，都可通过克隆 Git 仓库并安装来连接。数据库账簿用户和参与 MCP 服务开发的人员也请参阅 docs/CLIENTS.md。

连接自己的账簿

一次性转换：GnuCash 文件格式

MCP 服务只读取 GnuCash 文件的 SQLite 格式，不读取较旧的 XML 格式。转换步骤如下：

  1. 在 GnuCash 中打开账簿
  2. 选择 File → Save As
  3. 将“Data Format”改为 SQLite3
  4. 使用新文件名保存（例如 mybook-sqlite.gnucash）
  5. 保留 XML 原文件作为备份。

在 Linux（Debian/Ubuntu）上，“Data Format”下拉菜单中可能完全没有 SQLite3 选项——GnuCash 需要一个默认未安装的后端驱动程序。退出 GnuCash，安装该驱动程序，然后重新打开 GnuCash，选项便会出现：

sudo apt update && sudo apt install libdbd-sqlite3

此操作只需执行一次。之后，GnuCash 和 MCP 服务都会使用同一个 SQLite 文件。

GnuCash 3.8 或更新版本。 MCP 服务向账簿写入内容后，账簿会带有一个功能标记（“Use natural signs in budget amounts”），该标记由 GnuCash 3.8 引入；GnuCash 3.0–3.7 遇到不认识的功能标记时会拒绝打开账簿。GnuCash 3.8 及更高版本打开含有预算的账簿时，也会以相同方式添加此标记，因此只有仍在使用较旧 3.x 版本时才需要注意这一点。MCP 服务已通过 GnuCash 5.12 测试。

指定服务使用的账簿

使用安装包时，在 Claude Desktop 中的 GnuCash 扩展设置里选择账簿，然后重启 Claude Desktop。使用克隆安装时，将 GNUCASH_BOOK_PATH 设置为账簿的绝对路径；请参阅使用自己的账簿。

或者：将账簿保存在 PostgreSQL 或 MySQL 中

GnuCash 也可以将账簿保存在数据库中，而不是文件中，服务也支持这类账簿。将连接字符串传给它，而不是文件路径：

{
  "command": "/Users/yourname/.local/bin/gnucash-mcp",
  "args": ["--modules=all"],
  "env": {
    "GNUCASH_BOOK_URI": "postgresql://user:password@localhost:5432/gnucash",
    "GNUCASH_LOG_DIR": "/Users/yourname/gnucash-mcp-logs"
  }
}

在服务所在位置安装驱动——postgres 或 mysql（MariaDB 使用相同的驱动）。在克隆目录中（即 gnucash-mcp 文件夹；请参阅从源代码安装）：

uv tool install -e ".[postgres]" --reinstall

对于 MySQL / MariaDB，连接字符串为 mysql+pymysql://user:password@localhost:3306/gnucash，额外依赖为 [mysql]：uv tool install -e ".[mysql]" --reinstall。GnuCash 自己写入的较短形式 mysql:// 和 postgres:// 也可以使用；服务会使用额外依赖安装的驱动。

按上述方法从克隆目录安装，不要按名称安装：PyPI 上名为 gnucash-mcp 的项目属于另一个项目。

迁移现有账簿：在 GnuCash 中打开账簿，选择 文件 → 另存为，选择 postgres 或 mysql，然后填写连接详细信息。（在 Debian/Ubuntu 上，这些选项需要安装 sudo apt install libdbd-pgsql 或 libdbd-mysql，与 SQLite3 需要 libdbd-sqlite3 的方式相同；macOS 和 Windows 版本已包含这三者。） 保留文件——它仍然是完整有效的备份，保存着切换那一刻之前的所有内容。

切换前需要了解：

  • GNUCASH_BOOK_PATH 和 GNUCASH_BOOK_URI 不能同时设置——账簿要么是文件，要么是数据库；同时设置会导致启动错误，而不是随机决定将写入内容放到哪个账簿中。
  • 必须设置 GNUCASH_LOG_DIR。 审计日志和调试日志通常保存在账簿文件旁边的文件夹中；连接字符串没有“旁边”。
  • 每个服务只能使用一个账簿。 switch_book 根据文件名匹配，因此多账簿功能仅适用于文件。
  • 服务不再创建备份。 这是真正的取舍：自动安全保障之所以存在，是因为服务可以对文件创建快照，但无法对数据库创建快照。create_backup 会明确说明这一点，而不会假装可以备份。迁移真实账簿前，请设置定时运行的 pg_dump 或 mysqldump——请参阅 docs/RESTORE_FROM_BACKUP.md。
  • 服务在账簿名称所在的所有位置都会隐藏密码——包括工具结果、仪表板页眉和审计日志——也会在每条错误消息、日志行和启动错误中隐藏密码，包括数据库驱动写入的内容。以查询参数形式提供的密码（?password=…、sslpassword=…）也会以相同方式隐藏。
  • 将连接字符串放在 env 块中，不要放在命令行中。 --book-uri 可以使用，但命令行中的密码会显示给机器上所有用户，进程列表中也能看到。在 PostgreSQL 上，也可以完全不在字符串中填写密码，让驱动读取 PGPASSWORD 或 ~/.pgpass。

这两种方言都经过测试套件和 CI 验证：PostgreSQL 16 和 MariaDB 11 均使用真实服务进行测试。

选择模块集

--modules=all 是简单的默认选项——包含所有工具，共 86 个。 日常使用时，你可能会想要少一些。选择与你和服务交互方式相符的角色；你也可以单独选择每个角色背后的模块，以便更精细地控制。

角色提供的功能工具
core账簿基础功能——账户、交易、余额、槽位、审计日志、备份、资产负债表、对账。始终加载。29
bookkeeper除商业功能外的所有内容：报表、预算、计划交易、价格和投资批次。个人理财功能集。30
investor仅成本基础追踪和价格管理（bookkeeper 的子集）。13
business客户、供应商和员工；发票、账单、凭证和贷项通知单；销售税、付款条件、工作项目和供应商报表。27

选择一个或多个，用逗号分隔：

"args": ["--modules=bookkeeper"]            // personal finance
"args": ["--modules=investor"]              // self-directed investor
"args": ["--modules=business"]              // invoicing, freelance or small business
"args": ["--modules=bookkeeper,business"]   // everything (same as all)

无论如何都会添加 core。freelancer 和 business_complete 是 1.4 使用的名称，仍然受支持，并且表示 business。每个角色背后的模块（reconciliation、reporting、budgets、scheduling、tax_lots、portfolio 等）也可以单独选择——在仓库中运行 uv run gnucash-mcp --help 查看完整选项。

可以让它做什么

以下只是部分示例。用自然的方式提出这些要求即可——助手会帮你转换。

录入整份对账单

“这是我的 8 月份支票账户对账单。”（附上 PDF）

已将 31 条记录与账簿进行预演比对：24 条是新记录，6 条已录入（已认领），1 条需要检查——以下是对比结果。 确认后，我会一步完成本月的录入、分类和对账，并与期末余额核对一致。

一份对账单，两次调用，账簿核对平衡。试运行会先对每条记录进行分类并提供依据，然后才写入任何内容；如果账目无法核平，提交操作会拒绝整体写入，不会录入无法核平的月份。

记录交易

“今天我在 Safeway 花了 $47.50 买杂货，用 Visa 付款。”

已于 2026 年 4 月 30 日记录：从 Credit Card:Visa 支付 $47.50 至 Expenses:Groceries。描述：“Safeway”。

设置定期账单

“将房租设为定期账单。每月 1 日从支票账户支付 $1,850。”

已创建计划交易“Monthly Rent”：每月 $1,850，从 Assets:Checking 转至 Expenses:Rent。下次到期日：2026 年 5 月 1 日。

投资追踪

“我在 401(k) 账户中以每股 $170.99 的价格买入了 $1,000 的 VTSAX。”

已记录 VTSAX 买入：5.85 股，每股 $170.99。成本基础：$1,000.00。已创建投资批次，以便在你之后卖出时追踪资本利得。

为客户开具发票

“创建名为 Acme Corp 的客户，并为咨询服务向其开具 $1,500 的发票。”

已创建客户 Acme Corp（id 000005）和发票 000019：1× 咨询服务，单价 $1,500.00，总计 $1,500.00。尚未结清。准备好过账时告诉我。

如果你在 GnuCash 的“处理付款”对话框中打开服务器过账的发票，请先将其“过账至”账户设为该发票的应收账款账户：对话框只会列出过账到所选账户的单据。

外币发票

“向 Berlin Digital 开具 €4,200 的 Q1 顾问费发票，30 天后到期。”

已为 Berlin Digital GmbH 创建 EUR 发票 000020： 1× Q1 顾问费，EUR 4,200，总计 EUR 4,200。付款期限为净 30 天。对方付款时，我会自动将已实现的汇兑损益记入你的外汇账户。

提问

“今年我在各个供应商那里分别花了多少钱？”

Office Depot：$2,340（4 张账单，未付 $0） CloudHost Inc：$1,200（2 张账单，未付 $600） Legal Associates：$3,500（1 张账单，未付 $3,500） 账单总额 $7,040 / 已付 $2,940 / 未付 $4,100。

对账

“帮我根据 4 月份的对账单核对支票账户。”

[引导你完成对账：提取未对账的拆分记录，请你确认已结清的交易，计算滚动余额，将匹配的记录标记为已对账，并将不匹配项留给你调查。]

隐私与安全

你的账簿文件绝不会离开你的设备。 此服务是一个读取和写入本地文件的本地进程。你正在与之对话的 AI 助手（Claude Desktop 等）会看到工具调用的结果——也就是你在屏幕上会看到的相同内容——但文件本身始终留在原处。

每次写入都会记录。 人类可读的审计记录保存在账簿文件旁的 <your-book>.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

自动备份。 每个会话首次写入前（以及长期运行的会话跨入新的备份周期时），服务都会将账簿快照保存到 <your-book>.gnucash.mcp/backups/，这样一旦出错，你就可以回滚到已知的正常状态，而无需依赖 Time Machine 或自己的习惯。备份在标记为有效前会通过 PRAGMA integrity_check 验证；如果账簿自上次快照后没有更改，则会跳过备份。回滚流程请参阅 docs/RESTORE_FROM_BACKUP.md。

关于时间戳： 备份文件名使用 UTC 时间戳（适用于文件系统且在旅行和夏令时期间也不会产生歧义）；审计和调试日志则按本地日期保存为每日文件，符合你查找“周二发生了什么”的习惯。午夜前后，两者的日期可能相差一天——将备份与某日的日志对应时请注意这一点。

已对账的拆分条目会受到保护。 未经明确覆盖，服务会拒绝删除或修改已对账的拆分条目，因此不够谨慎的提示词不会悄悄破坏你最近一次的银行对账结果。

作废 ≠ 删除。 当你告诉 AI“作废这笔交易”时，它会使用 GnuCash 正规的会计作废操作——保留交易以供审计追踪，并将数值归零。删除则是破坏性操作；AI 会告诉你它将执行哪种操作。

免责声明： 本软件根据 MIT License 按“原样”提供，不提供任何形式的保证。作者不对因使用本软件而导致的任何数据丢失、损坏或财务差异承担责任。你须自行负责维护备份并核实账簿的准确性。

已知限制

  • 不要同时在 GnuCash 桌面应用和服务中编辑账簿。 服务遵守 GnuCash 的锁定机制，但不会自行持有锁（每次调用只会打开账簿一次），因此 GnuCash 不会警告你服务正在使用账簿。
  • 启用了“Use Trading Accounts”的账簿： 涉及多种货币或商品的交易（包括股票和基金购买）会被拒绝，因为服务目前还无法像 GnuCash 那样写入交易拆分条目。请在 GnuCash 桌面应用中录入此类交易；所有单一货币的操作均可照常进行。
  • GnuCash 3.8 或更高版本。 服务写入过的账簿会带有一个功能标记，GnuCash 3.0–3.7 无法打开此类账簿。
  • 外币支出和收入在支出和收入报告中按每月收盘汇率估值，而非按支付款项的现金估值；cash_flow 报告则反映现金。

完整列表请见 CHANGELOG.md。

限制 AI 可查看的内容

每个工具的描述都位于 AI 的系统提示词中，每条消息都会占用上下文。将工具集缩小到你实际使用的范围，可以降低每次对话的成本。有关四种角色（core、bookkeeper、investor、business），请参阅上文的选择模块集。

你也可以将 GNUCASH_MCP_MODULES=core,bookkeeper 设置为环境变量，代替 JSON 参数中的 --modules=...。

v1.5.0 版本更新内容

  • 将账簿存储在数据库中。 让服务连接到 GnuCash 保存在 PostgreSQL 或 MySQL/MariaDB 中的账簿，不再局限于 SQLite 文件 — 参见或者：将账簿保存在 PostgreSQL 或 MySQL 中。 PostgreSQL 支持由 @vchatela贡献。
  • 所有内容都按 GnuCash 桌面应用的存储方式保存。 定期交易会在桌面应用的“自上次运行以来”中执行；预算、发票、贷项通知单、作废记录和价格在两者中的读取结果相同；发票总额也与 GnuCash 自身的结果精确到分。要从 1.4 升级？请先阅读升级指南。
  • 预付款。 将客户或供应商的超额付款记录为代其持有的款项，用这笔款项结算后续发票，并在取消已付款发票过账时保留付款记录。
  • 每个交易工具都支持编号和单据链接，并使用编号检查重复项。
  • 仪表板上提供账户科目表，让助手在提问前就能了解每个账户的位置。
  • 根据源代码构建的示例账簿，均按各自国家／地区的税务惯例（美国／华盛顿、德国、中国）核验，并更新至构建当天的最新状态。

早期版本请参阅 CHANGELOG.md。

故障排除

没有 🔨 锤子图标，或显示“找不到工具”
  • 完全退出 Claude Desktop，然后重新打开。（仅关闭窗口还不够 — 必须退出应用程序。）
  • 确认配置中的路径是绝对路径且正确无误。
  • 检查 JSON 中是否有尾随逗号 — 它们会导致配置静默失效。
“找不到账簿”
  • 使用绝对路径，不要使用 ~ 或相对路径。
  • Mac/Linux：/Users/yourname/Documents/book.gnucash
  • Windows：C:\\Users\\yourname\\Documents\\book.gnucash （双反斜杠 — JSON 格式要求）
“无法打开账簿”／piecash 错误
  • 确认账簿使用的是 SQLite 格式，而不是 XML。
  • 确保 GnuCash 没有打开同一本账簿 — 这会造成文件锁定。 服务会遵循 GnuCash 的锁定机制，但刻意不加自己的锁（每次调用只会占用账簿一次），因此 GnuCash 可以在服务正在使用账簿时打开它，且不会发出警告。不要同时在两处编辑。
  • 尝试直接在 GnuCash 中打开账簿，确认文件未损坏。
Docker：“同时设置了 GNUCASH_BOOK_PATH 和 GNUCASH_BOOK_URI”

镜像默认将 GNUCASH_BOOK_PATH 指向随镜像附带的演示账簿。若要通过它提供数据库账簿，请在命令行中将该默认值清空（-e GNUCASH_BOOK_PATH=），并同时设置 GNUCASH_BOOK_URI；若要提供挂载的文件，请将 GNUCASH_BOOK_PATH 设为挂载路径，并以文件所有者身份运行容器（--user "$(id -u):$(id -g)"）。

“找不到账户”
  • 使用完整账户路径：Expenses:Groceries，而不仅是 Groceries。
  • 或者让助手列出账户：“列出我的账户。”
客户端重启后出现多个服务进程

Claude Desktop（以及其他一些 MCP 客户端）在重新启动时可能会短暂启动两到三个服务副本。这是客户端行为，不是服务缺陷，而且基本无害：服务会在每次请求时打开账簿，并在调用间释放文件锁，因此进程重叠只会持续片刻。如果客户端重启后持续出现 Lock on the file 错误，请彻底退出客户端，使用 pgrep -fl gnucash-mcp 确认没有残留进程，然后重新启动。

出现错误
  • 打开 <your-book>.gnucash.mcp/audit/ 中的审计日志 — 服务首次运行以来的每次写入都记录在其中，并附有变更前后的详情。
  • 如果需要回滚，docs/RESTORE_FROM_BACKUP.md 中提供了操作说明。

支持本项目

如果 gnucash-mcp 对你有用，可以考虑请我喝杯咖啡。这有助于让开发持续进行。

面向开发者

贡献者指南和设计说明位于 CLAUDE.md。快速了解：

uv sync --extra dev
uv run pytest                       # 3,300+ tests as of v1.5.0, parallel by default
uv run ruff check src/ tests/
uv run black --check src/ tests/

已安装的 gnucash-mcp 命令会实时跟踪你的克隆：它会提供当前检出分支上的代码，因此切换分支后，在下次重启时提供的代码也会随之切换——便于测试，但要记得这一点，免得忘了自己还在某个分支上。若要运行另一个检出（第二个工作树）而不动安装内容，uv run --directory PATH gnucash-mcp 仍可运行你指定的任意目录。

该服务基于 piecash（用于访问 GnuCash SQLite 账簿的 Python 接口）和 MCP Python SDK 构建。 代码约有 18,000 行 Python 源码和 20,000 行测试，并采用模块化设计，因此禁用的模块不会带来任何运行时开销。

许可证

MIT。

致谢

  • GnuCash — 这款免费开源的会计软件，让本服务能够以对话方式与之交互。
  • piecash — 用于访问 GnuCash SQLite 账簿的 Python 接口。
  • MCP Python SDK — Model Context Protocol 的实现。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。