AI导哈

财务数据查询服务

GnuCash MCP Server是一个基于GnuCash Python绑定的服务，允许AI助手读取和查询财务数据。

  • by jmceleney
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 jmceleney/gnucash-mcp

使用说明

GnuCash MCP服务器

一 MCP（模型上下文协议） 服务器 GnuCash，允许AI助手读取和查询您的财务数据。

此服务器使用 官方GnuCash Python绑定，提供与所有GnuCash文件格式的完全兼容性，包括gzip压缩的XML和SQLite数据库。

先决条件

GnuCash Python绑定必须安装在您的系统上。这些是GnuCash本身的一部分 无法通过pip安装.

Ubuntu/Debian

sudo apt install gnucash python3-gnucash

菲多拉

sudo dnf install gnucash python3-gnucash

Arch Linux

sudo pacman -S gnucash

验证安装

python3 -c "import gnucash; print('GnuCash bindings OK')"

快速开始

# Clone the repository
git clone https://github.com/jmceleney/gnucash-mcp.git
cd gnucash-mcp

# Create a virtual environment with access to system packages
python3 -m venv --system-site-packages .venv
source .venv/bin/activate
pip install mcp

# Run the server (GNUCASH_FILE is required)
GNUCASH_FILE=/path/to/your/finances.gnucash python3 server.py

配置

克劳德代码

claude mcp add gnucash \
  -e GNUCASH_FILE=/path/to/your/finances.gnucash \
  -- /path/to/gnucash-mcp/.venv/bin/python3 /path/to/gnucash-mcp/server.py

要启用写入模式（允许创建事务）：

claude mcp add gnucash \
  -e GNUCASH_FILE=/path/to/your/finances.gnucash \
  -- /path/to/gnucash-mcp/.venv/bin/python3 /path/to/gnucash-mcp/server.py --write

克劳德桌面版

添加到配置文件中：

  • Linux: ~/.config/claude/claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "gnucash": {
      "command": "/path/to/gnucash-mcp/.venv/bin/python3",
      "args": ["/path/to/gnucash-mcp/server.py"],
      "env": {
        "GNUCASH_FILE": "/path/to/your/finances.gnucash"
      }
    }
  }
}

对于写入模式，添加 "--write" 到args数组。

可用工具

读取工具（始终可用）

工具 说明
list_accounts() 列出所有帐户及其类型。
get_account_balance(account_name) 获取余额（支持部分名称匹配）。
get_transactions(account_name, limit) 获取最近的交易记录（默认值：20）。
search_accounts(query) 按名称搜索帐户（不区分大小写）。
get_account_info(account_name) 获取详细的帐户信息。

写入工具（必需 --write 旗帜）

工具 说明
add_transaction(from_account, to_account, amount, description, date, memo) 在两个账户之间创建交易。
commit() 将待处理的更改保存到磁盘（退出时也会自动保存）。

帐户名称

使用点符号： Assets.Current Assets.Checking Account

部分匹配工作：

  • Checking Account 火柴 Assets.Current Assets.Checking Account
  • electric 火柴 Expenses.Utilities.Electric

查询示例

  • “我的支票账户余额是多少？”
  • “显示最近的储蓄交易”
  • “列出所有费用账户”
  • “搜索包含‘实用程序’的帐户”
  • “将50美元从支票转入储蓄”（写入模式）

故障排除

“没有名为'gnucash'的模块”

通过系统包管理器安装GnuCash Python绑定。

“没有名为'mcp'的模块”

激活venv并安装： pip install mcp

文件已锁定

如果GnuCash桌面应用程序未运行，服务器会自动删除过时的锁文件。如果GnuCash已打开，请先关闭它。

“未设置GNUCASH_FILE环境变量”

这 GNUCASH_FILE 环境变量是必需的。在运行服务器或MCP配置中设置它。

为什么不使用uvx/pipx？

这些工具创建了无法访问系统包的隔离环境。GnuCash Python绑定仅作为系统包可用，因此我们必须使用 --system-site-packages.

局限性

  • 系统相关性：需要在系统范围内安装GnuCash
  • 单个文件：一次打开一个文件
  • 相同货币交易：写入模式仅支持相同货币的账户之间的交易

许可证

麻省理工学院

相关 MCP