支持MCP的个人记账应用ezBookkeeping

发表于 分类于 Waline： 阅读次数： 本文字数： 4.3k 阅读时长 ≈ 4 分钟
ezBookkeeping 是轻量级、自托管的个人理财应用程序，具有时尚、用户友好的界面和强大的记账功能。

简介

什么是 ezBookkeeping ？

ezBookkeeping 是一款轻量、自托管 (self-hosted) 的个人记账应用，拥有简洁美观的用户界面与强大的记账功能。它以“简单易用、易于部署”为设计理念，对系统资源的需求极低，非常适合部署在 MicroServer、NAS 设备，甚至树莓派上使用。

主要特点

  1. 开源与自托管： 用户可以完全控制自己的数据，保护隐私。
  2. 轻量与快速：优化性能，即使在低资源环境中也能流畅运行。
  3. 简单安装：支持 Docker 部署，兼容 SQLite、MySQL 和 PostgreSQL 数据库。
  4. 跨平台支持：兼容 Windows、macOS 和 Linux，支持 x86、amd64 和 ARM 架构。
  5. 用户友好的界面：针对移动和桌面设备优化的 UI，支持 PWA（渐进式 Web 应用）。
  6. 强大的记账功能：支持两层账户和分类、交易附加图片、位置跟踪、定期交易等。
  7. 数据导入/导出功能：支持多种格式（如 CSV 、Firefly III、随手记、支付宝以及微信账单等多种格式）的数据导入和导出。
  8. 安全性：提供双因素认证、登录限速和应用锁等安全措施。
  9. 多语言和多货币支持：自动汇率更新和多时区意识，便于国际用户使用。

应用场景

  • 个人财务管理：适合个人用户管理和跟踪日常开支、收入和财务状况。
  • 家庭预算规划：家庭用户可以利用该应用进行预算管理和开支分析。
  • 小型企业记账：小型企业可使用该工具进行财务记录和报表生成。
  • 数据迁移与整合：支持从其他财务软件迁移数据，方便用户集中管理财务信息。

ezBookkeeping 是一个灵活、高效的财务管理工具，适合希望控制个人财务的用户和小型企业。

安装

在群晖上以 Docker 方式安装。

在注册表中搜索 ezbookkeeping ，选择第一个 mayswind/ezbookkeeping，版本选择 latest。

本文写作时， latest 版本对应为 0.10；

老苏选择了 MySQL 做数据库，但是没有用群晖自带的，这样适用范围更广，无论你使用什么类型的 NAS，只要支持 docker 环境就可以

因为涉及多容器，所以采用 docker-compose 安装。将下面的内容保存为 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
version: "3"

services:
  ezbookkeeping:
    image: mayswind/ezbookkeeping
    container_name: ezbookkeeping
    restart: unless-stopped
    ports:
      - 8422:8080
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ./storage:/ezbookkeeping/storage
      - ./log:/ezbookkeeping/log
    #  - ./ezbookkeeping.ini:/ezbookkeeping/conf/ezbookkeeping.ini
    environment:
      - EBK_DATABASE_TYPE=mysql
      - EBK_DATABASE_HOST=mysql:3306
      - EBK_DATABASE_NAME=ezbookkeeping
      - EBK_DATABASE_USER=ezbookkeeping
      - EBK_DATABASE_PASSWD=ezbookkeeping
      - EBK_LOG_MODE=file
      - EBK_SECURITY_SECRET_KEY=its_should_be_a_random_string
      - EBK_MCP_ENABLE_MCP=true
    # depends_on:
    #  mysql:
    #    condition: service_healthy

  mysql:  
    image: mysql:8.0 
    container_name: ezbookkeeping-mysql
    restart: unless-stopped
    volumes:  
        - ./data:/var/lib/mysql
    environment:  
        - MYSQL_DATABASE=ezbookkeeping  
        - MYSQL_USER=ezbookkeeping  
        - MYSQL_PASSWORD=ezbookkeeping  
        - MYSQL_ROOT_PASSWORD=ezbookkeeping
    healthcheck:  
        test: ["CMD", "mysqladmin", "ping", "-p ezbookkeeping"]  
        retries: 3  
        timeout: 5s
  • 容器 ezbookkeeping 的环境变量
环境变量 说明
EBK_DATABASE_TYPE 数据库类型，设置为 mysql
EBK_DATABASE_HOST 数据库主机地址，通常为 mysql:3306
EBK_DATABASE_NAME 数据库名称，设置为 ezbookkeeping
EBK_DATABASE_USER 连接数据库的用户名，设置为 ezbookkeeping
EBK_DATABASE_PASSWD 连接数据库的密码，设置为 ezbookkeeping
EBK_LOG_MODE 日志模式，设置为 file
EBK_SECURITY_SECRET_KEY 随机字符串，用于安全密钥
EBK_MCP_ENABLE_MCP 启用 MCP 功能，设置为 true
  • 容器 mysql 的环境变量
环境变量 说明
MYSQL_DATABASE 创建的数据库名称，设置为 ezbookkeeping
MYSQL_USER 数据库用户的名称，设置为 ezbookkeeping
MYSQL_PASSWORD 数据库用户的密码，设置为 ezbookkeeping
MYSQL_ROOT_PASSWORD MySQL 根用户的密码，设置为 ezbookkeeping

更多更详细的设置，请参考官方文档： https://ezbookkeeping.mayswind.net/zh_Hans/configuration

然后执行下面的命令

1
2
3
4
5
6
7
8
9
10
11
12
13
# 新建文件夹 ezbookkeeping 和 子目录
mkdir -p /volume1/docker/ezbookkeeping/{data,log,storage}

# 进入 ezbookkeeping 目录
cd /volume1/docker/ezbookkeeping

# 修改权限
chmod a+rw {log,storage}

# 将 docker-compose.yml 放入当前目录

# 一键启动
docker-compose up -d

运行

在浏览器中输入 http://群晖IP:8422 就能看到登录界面

第一次需要注册一个用户

如果不想麻烦，可以启用 使用预设交易分类

主界面

首先要有账户

可以是现金、借记卡、信用卡等，老苏建的账户名称为 测试账户

然后就可以添加交易数据了

生成 MCP 令牌

ezBookkeeping 支持 MCP 服务器，安装时，我们已经在环境变量中已经设置EBK_MCP_ENABLE_MCP=true，接下来我们还需要生成 MCP 令牌

请注意，ezBookkeeping 的 MCP 令牌与其他类型的令牌不同，MCP 令牌没有过期时间；

有两种办法

方法一

第一种是通过图形界面，相对简单

右上角 –> 用户设置 –> 安全 –> 生成 MCP 令牌

输入当前账号的密码

生成令牌

启用配置，可以看到 json 配置格式

之后是看不到的，只能重新生成

方法二

第二种是命令行方式

1
2
3
4
5
6
7
8
# 进入容器
docker exec -it --user root ezbookkeeping /bin/sh

# 生成 MCP 令牌的命令
./ezbookkeeping userdata user-session-new --username <用户名> --type mcp

# 示例
./ezbookkeeping userdata user-session-new --username laosu --type mcp

Cherry Studio

以 Cherry Studio 为例添加 ezBookkeeping MCP

  • 名称：主要用于识别，例如：ezBookkeeping
  • 类型：选择 streamableHttp 协议
  • URL：为 http://群晖IP:8422/mcp
  • 请求头： 为 Authorization=Bearer {token}

如果使用 json

1
2
3
4
5
6
7
8
9
10
11
{
    "mcpServers": {
        "ezbookkeeping-mcp": {
            "type": "streamable-http",
            "url": "http://{domain}/mcp",
            "headers": {
                "Authorization": "Bearer {token}"
            }
        }
    }
}

如果设置没问题，可以看到可用的工具

为了确保大模型能正确理解什么是今天，还需要加个时间 mcp

如果使用 json

1
2
3
4
5
6
7
8
{
    "mcpServers": {
        "mcp-server-time": {
            "command": "uvx",
            "args": ["mcp-server-time"]
        }
    }
}

新建一个助手

启用 Time MCP 和 ezBookkeeping MCP

现在可以用自然语言进行记账了

回到 ezBookkeeping 的 web 界面，可以看到记录成功了

参考文档

mayswind/ezbookkeeping: A lightweight personal bookkeeping app hosted by yourself.
地址：https://github.com/mayswind/ezbookkeeping

Home | ezBookkeeping
地址：https://ezbookkeeping.mayswind.net/

ezBookkeeping
地址：https://ezbookkeeping-demo.mayswind.net