关于 UnderDoc Tutorial - Expense Analytics using GenAI and MCP server for SQLite DB
这是一个以 SQLite 支出数据为例的教程，展示如何从收据和发票图片提取结构化数据，并通过 Claude Desktop 与自然语言进行分析。适合希望了解 UnderDoc、SQLite 和 MCP 配合流程的用户。
主要功能
- 01从收据和发票图片提取支出数据
- 02将结构化记录保存到 SQLite
- 03使用 Claude Desktop 进行自然语言分析
适用场景
- 01将图片中的支出信息整理进数据库
- 02通过自然语言查询和分析支出记录
MCP 相关
教程使用 SQLite MCP 服务，让 Claude Desktop 访问数据库中的支出记录并进行分析。
配置
本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。
我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。
工具
本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。
详细介绍
UnderDoc 教程 - 使用 GenAI 和用于 SQLite DB 的 MCP 服务进行费用分析
- UnderDoc 教程 - 使用 GenAI 和用于 SQLite DB 的 MCP 服务进行费用分析
简介
在我之前的教程中，我介绍了如何从图片中提取结构化费用数据，将其存储到 SQLite DB 中，并使用 Metabase 进行费用分析。
在本教程中，我将介绍如何使用 GenAI 和 SQLite MCP 服务，通过与大模型进行自然语言对话来执行费用分析。
本教程重点介绍使用 GenAI（Claude Desktop）和 SQLite MCP 服务，并假设数据库中已填入 UnderDoc 费用记录。你可以按照之前的教程操作，直到“提取数据并保存到 DB”一节（跳过其余与 Metabase 相关的部分）。如果你想快速了解 MCP 服务的工作方式，也可以在此处下载包含 20 条费用示例记录的 SQLite DB 示例。
要完成本教程，你需要具备以下条件：
- 一台运行 MacOS 的笔记本电脑或台式电脑
- uv（一款用于运行 SQLite MCP 服务的 Python 运行时和软件包管理器）
- git（用于从 github 克隆 MCP 服务源代码）
- Claude Desktop（本教程使用的 GenAI 应用，支持 MCP 服务）
- Sqlite DB
对于尚未阅读之前教程的读者，我在此重现了相关步骤，方便参考。如果你已经准备好 SQLite DB，可以跳转至“使用自然语言进行费用分析”一节。
概述
本教程将使用以下组件完成各种任务：
- UnderDoc，用于从收据、发票和请款单图片中提取数据
- uv，用于管理 Python 运行环境并运行 MCP 服务
- SQLite，用于存储提取的数据
- Claude Desktop for Mac，用于通过 MCP 服务和大模型进行费用分析
什么是 MCP
讨论 MCP（Model Context Protocol）的文章太多了，因此这里不再赘述。简单来说，MCP 为大模型与回答用户问题所需的各种资源和工具提供了一种标准化的交互方式。
目前已有不少支持 MCP 服务的工具，例如 Claude desktop、Cursor IDE 等。许多其他生成式 AI 提供商（例如 OpenAI、Google 等）也宣布在其服务中支持 MCP。
GitHub 上的开源 MCP 仓库提供了一份参考服务列表。其中有一个用于集成 SQLite DB 的服务，本教程将会用到它。
前提条件
获取 UnderDoc API 密钥
本教程的关键步骤是从图片中提取费用信息，并将其转换为适合存入数据库以供探索的结构化数据（例如商店名称、金额、货币、推断出的类别等）。我们将使用 UnderDoc，这是一个性价比高的平台（提供免费套餐），可用于完成这项任务。该工具也能很好地处理多语言图片。
使用 UnderDoc 很简单，只需在其开发者门户注册并获取 API 密钥。
步骤 1：注册
首先，访问 UnderDoc Developer Portal 注册页面。
输入电子邮件和密码，然后确认注册。
注册成功后，你会收到一封电子邮件。登录前需要先验证电子邮件地址。
步骤 2：登录
注册成功并验证电子邮件后，即可登录 UnderDoc Developer Portal。
步骤 3：从“Key Management”页面获取密钥
在左侧选择“Key Management”。
在 Key Management 页面中，点击眼睛图标以显示密钥，然后复制该密钥，供本教程后续使用。
现在你已经获得 UnderDoc API 密钥，可以继续完成本教程的其余部分。
安装 uv
运行 SQLite MCP 服务需要使用“uv”。安装说明请参阅其网站。最简单的方式是使用 brew 安装：
brew install uv
安装 Python 3.12
本教程已使用 Python 3.12 进行测试。在 Mac 上安装它最简单的方式是通过 Homebrew 安装。请运行以下命令。
brew install [email protected]
安装 sqlite 命令行界面
提取的费用数据将保存在本地 SQLite DB 中。我们将使用 SQLite 验证数据库及其中存储的数据。安装时同样使用 Homebrew。
brew install sqlite
所有前提条件至此已准备完毕，接下来进行环境设置！
环境设置
克隆本教程的项目
本教程提供了所需的所有 Python 脚本和一些示例图片。使用以下命令从 GitHub 克隆项目。
git clone https://github.com/under-doc/underdoc-expense-analytics-tutorial.git
克隆后，切换到项目文件夹。例如，我的文件夹如下：
/Users/clarenceho/workspace/underdoc/underdoc-expense-analytics-tutorial
在此文件夹中，你会看到一些文件夹和文件。概览如下：
- README.md：本文件
- model.py：用于模型类的 Python 脚本
- main.py：用于提取流程的 Python 脚本
- requirements.txt：本项目所需的 Python 库包
- receipt-images：存放费用图片的文件夹。你可以看到提供的 20 张示例图片
- metabase-data：用于存储 Metabase 和 UnderDoc 数据库
设置 Python 虚拟环境并安装所需软件包
接下来，为本教程创建 Python 虚拟环境并安装所需软件包。按顺序运行以下命令。
# Step 1: Create a Python virtual environment in the folder venv using Python 3.12
python3.12 -m venv venv
# Step 2: Activate the Python virtual environment
source venv/bin/activate
# Step 3: Install the required Python packages
pip install -r requirements.txt
环境验证
运行以下命令，验证 Python 环境。
pip list
你应该会看到如下列表。
Package Version
------------------------- -----------
aiosignal 1.3.2
annotated-types 0.7.0
anyio 4.9.0
attrs 25.3.0
boto3 1.37.22
botocore 1.37.22
certifi 2025.1.31
charset-normalizer 3.4.1
click 8.1.8
filelock 3.18.0
frozenlist 1.5.0
h11 0.14.0
httpcore 1.0.7
httpx 0.28.1
idna 3.10
jmespath 1.0.1
jsonschema 4.23.0
jsonschema-specifications 2024.10.1
msgpack 1.1.0
packaging 24.2
pip 25.0
protobuf 6.30.2
pydantic 2.11.0
pydantic_core 2.33.0
pydantic-settings 2.8.1
python-dateutil 2.9.0.post0
python-dotenv 1.1.0
PyYAML 6.0.2
ray 2.44.1
referencing 0.36.2
requests 2.32.3
rpds-py 0.24.0
s3transfer 0.11.4
six 1.17.0
sniffio 1.3.1
SQLAlchemy 2.0.40
sqlmodel 0.0.24
typing_extensions 4.13.0
typing-inspection 0.4.0
underdoc 0.4.2
urllib3 2.3.0
初始化 SQLite 数据库（可选）
我们需要一个空的 SQLite 数据库文件来存储提取的费用数据。本仓库已提供一个（位于 metabase-data/underdoc.db）。如果需要初始化数据库，请运行以下命令：
sqlite3 metabase-data/underdoc.db
将费用图片复制到 receipt-images 文件夹
脚本会处理 receipt-images 文件夹中的所有图片。你可以使用提供的示例图片，也可以将自己的图片复制到该文件夹中进行分析。
如果你已经跟着本教程操作到这里，我非常感谢你！现在，我们可以开始从图片中提取数据并保存到数据库了。
执行数据提取并保存到数据库
运行脚本前，请设置 UnderDoc API 密钥的环境变量，因为脚本会使用该密钥与 UnderDoc 交互。
export UNDERDOC_API_KEY=<your_api_key>
环境设置完成并准备就绪后，将数据提取到数据库很简单。只需运行以下命令：
python main.py
该脚本使用 UnderDoc Python SDK 与 UnderDoc 的文档理解 API 交互，获取返回的结构化数据，然后将其存储到 SQLite 数据库中。根据笔记本电脑的硬件情况，脚本还会尝试并行提取多张图片。
脚本运行需要一些时间。如果成功，你会看到类似以下的输出。
python main.py
2025-04-01 12:38:25,873 - __main__ - INFO - UnderDoc Tutorial - Extract expense data from imagesand persist to DB
2025-04-01 12:38:25,873 - __main__ - INFO - Extracting expense data and persist to DB
2025-04-01 12:38:25,873 - __main__ - INFO - Extracting expense data from images - will take some time
2025-04-01 12:38:25,873 - underdoc.underdoc_client - INFO - UnderDoc client initialized successfully
2025-04-01 12:38:25,873 - underdoc.underdoc_client - INFO - Extracting expense data from file pattern: receipt-images/*.*, execution mode: BatchExecutionMode.Parallel
2025-04-01 12:38:27,370 INFO worker.py:1852 -- Started a local Ray instance.
2025-04-01 12:39:16,704 - underdoc.underdoc_client - INFO - Extracted 20 expense data from 20 images
2025-04-01 12:39:16,704 - __main__ - INFO - Extracted expense data from images completed successfully
2025-04-01 12:39:16,733 - __main__ - INFO - Expense data saved to DB
数据验证
运行以下命令，验证 SQLite 数据库中的数据。
sqlite3 metabase-data/underdoc.db
在“sqlite>”提示符下，输入以下命令列出表。
sqlite> .tables
你应该会看到一个名为“myexpense”的表。
sqlite> .tables
myexpense
要列出表中的记录，请输入以下命令。
sqlite> select * from myexpense;
你应该能看到所有费用记录，类似如下内容。
sqlite> select * from myexpense;
1|2023-08-08 00:00:00.000000|Invoice|Uber||Misc|TWD|1642.0|receipt-images/expense_008.png
2|2025-01-02 00:00:00.000000|Receipt|函太郎 Tokyo店|東京都千代田区丸の内1-9-1|Food|JPY|2299.0|receipt-images/expense_020.jpg
3|2023-01-31 00:00:00.000000|Invoice|Google|70 Pasir Panjang Road, #03-71
Mapletree Business City
Singapore 117371|Google Workspace|USD|18.0|receipt-images/expense_009.png
4|2025-01-04 00:00:00.000000|Receipt|AEON|イオン新潟西店|Groceries|JPY|3923.0|receipt-images/expense_019.jpg
5|2024-07-29 00:00:00.000000|Invoice|台灣自來水股份有限公司|236新北市土城區學享街63、65號|Utilities|TWD|149.0|receipt-images/expense_018.png
6|2023-03-02 00:00:00.000000|Receipt|AXA 安盛|5/F, AXA Southside, 38 Wong Chuk Hang Road, Wong Chuk Hang, Hong Kong|Policy Premium Payment|HKD|2577.48|receipt-images/expense_001.png
7|2024-09-07 00:00:00.000000|Invoice|48.Lindberg by Puyi|Shop OT 316, Level 3, Ocean Terminal, Harbour City, Tsimshatsui, Kowloon, Hong Kong|optical|HKD|12498.0|receipt-images/expense_015.jpg
8|2021-04-27 00:00:00.000000|Receipt|深仔記|尖沙咀亞厘道29-39號
九龍中心地下A舖|Food|HKD|39.0|receipt-images/expense_014.png
9|2022-10-21 00:00:00.000000|Invoice|中華電信|台北營運處|Telecommunication|TWD|588.0|receipt-images/expense_002.png
10|2021-05-27 00:00:00.000000|Receipt|OUTBACK STEAKHOUSE|Shop 304, 3/F,Silvercord
Tsim Sha Tsui, Kowloon.|food|HKD|78.0|receipt-images/expense_016.png
11|2023-03-23 00:00:00.000000|Invoice|新加坡商蝦皮娛樂電商有限公司台灣分公司|台灣分公司|Electronics|TWD|3990.0|receipt-images/expense_017.png
12|2025-03-04 00:00:00.000000|Receipt|namecheap|4600 East Washington Street. Suite 305, Phoenix, AZ 85034 USA|web services|USD|47.88|receipt-images/expense_003.png
13|2023-07-29 00:00:00.000000|Invoice|CLP|DIAMOND HILL KOWLOON|Electricity|HKD|903.0|receipt-images/expense_007.png
14|2024-12-18 00:00:00.000000|Invoice|RATING AND VALUATION DEPARTMENT||Misc|HKD|3130.0|receipt-images/expense_013.png
15|2023-05-02 00:00:00.000000|Invoice|Manning Publications Co.|20 Baldwin Road Shelter Island, NY 11964|Books|USD|26.39|receipt-images/expense_012.png
16|2021-08-25 00:00:00.000000|Invoice|香港寬頻 HONG KONG BROADBAND NETWORK||Misc|HKD|282.0|receipt-images/expense_006.png
17|2021-08-09 00:00:00.000000|Invoice|Water Supplies Department|FLAT H, 30/F, BLOCK 1
GRAND VIEW GARDEN
DIAMOND HILL, KOWLOON|Water bill|HKD|287.8|receipt-images/expense_010.png
18|2025-01-06 00:00:00.000000|Receipt|NIPPON Rent-A-Car|越後湯沢営業所|rental car|JPY|46750.0|receipt-images/expense_004.jpg
19|2021-09-29 00:00:00.000000|Receipt|潮發大藥房|九龍九龍城衙前圍道88號地下|Medicine|HKD|515.0|receipt-images/expense_005.png
20|2022-09-14 00:00:00.000000|Invoice|Apple||Cloud Storage|TWD|90.0|receipt-images/expense_011.png
如你所见，提供的示例图片包含英文、中文和日文。你还可以查看每条记录对应的源图片文件。
使用自然语言分析费用
现在，我们已从收据／发票图片中提取费用数据并存储到数据库中，可以使用 Claude Desktop 和用于 SQLite 的 MCP 服务进行分析。
首先，我们需要安装 Claude Desktop（如果你之前没有使用过）。
安装 Claude Desktop
按照 Anthropic 网站上的说明下载并安装 Claude Desktop。然后根据需要注册账号。
从 GitHub 克隆参考 MCP 服务的源代码
撰写本文时，使用用于 SQLite 数据库的参考 MCP 服务需要从其 GitHub 仓库克隆源代码。
git clone https://github.com/modelcontextprotocol/servers.git
克隆后，用于 SQLite 的 MCP 服务源代码位于子文件夹“servers/src/sqlite”中。你可以参阅其 README 文件，了解 MCP 服务的功能和安装说明。
为 Claude Desktop 安装 SQLite MCP 服务
要为 Claude Desktop 安装 MCP 服务，需要编辑应用的配置文件。在 Mac 上，文件位置为：
~/Library/Application Support/Claude/claude_desktop_config.json
使用任意编辑器打开该文件，并将以下代码片段添加到文件中：
"mcpServers": {
"sqlite": {
"command": "uv",
"args": [
"--directory",
"<parent_of_servers_repo>/servers/src/sqlite",
"run",
"mcp-server-sqlite",
"--db-path",
"<underdoc_db_file_path>"
]
}
}
如果之前已经安装过 MCP 服务，只需将“sqlite”部分追加到“mcpServers”部分即可。
请记得替换以下占位符：
- <parent_of_servers_repo>：克隆 MCP 服务源代码的文件夹
- <underdoc_db_file_path>：underDoc.db 文件的路径
例如，在我的环境中，代码片段如下：
"mcpServers": {
"sqlite": {
"command": "uv",
"args": [
"--directory",
"/Users/clarenceho/workspace/mcp/servers/src/sqlite",
"run",
"mcp-server-sqlite",
"--db-path",
"/Users/clarenceho/workspace/underdoc/sqlite/underdoc.db"
]
}
}
修改后，重启 Claude Desktop。
注意：uv（你会发现它是启动 MCP 服务的命令）也需要访问文件夹 ~/.local/share/uv 和 ~/.local/share/python。我第一次安装 MCP 服务后启动 Claude Desktop 时，遇到了类似“Permission denied to folder ~/.local/share/uv”的错误。如果你遇到相同的错误，请创建这些文件夹并授予自己访问权限。例如，在我的环境中：
sudo mkdir ~/.local/share/uv
sudo mkdir ~/.local/share/python
sudo chown <your-username> ~/.local/share/uv
sudo chown <your-username> ~/.local/share/python
在 Claude Desktop 中验证 MCP 服务
让我们验证 SQLite MCP 服务是否已成功安装到 Claude。
在 Claude 的主聊天窗口中，你会看到一列图标按钮。点击下图中突出显示的“MCP Tools 图标”。
此时会弹出一个对话框，显示可供其大模型调用的 MCP 工具列表（由已配置的 MCP 服务提供）。以下截图为示例：
我突出显示了 SQLite 服务提供的 2 个工具。这些是大模型可用于从 SQLite DB 中检索信息和数据的函数调用。由于 MCP 服务配置中包含 UnderDoc DB 文件，Claude 将能够显示费用表的架构和数据。SQLite MCP 服务提供的完整工具列表可在此处查看。在此对话框中看到这些工具，意味着你已成功将 SQLite MCP 服务安装到 Claude。
截图中还可以看到其他工具，因为我也安装了“filesystem”参考服务。
UnderDoc 费用（SQLite）DB 概览
我们先使用以下查询，请 Claude 查看 SQLite DB：
Show me the tables in the sqlite db
提交查询后，Claude 发现可以使用 SQLite MCP 服务的“list_tables”工具来回答我的问题。出于安全考虑，它会请求你允许运行这些工具。
点击“Allow for this chat”，允许 Claude 运行该工具。
Claude 会运行该工具，并回复说它找到了 1 个表“myexpense”，然后询问你是否要查看该表的结构。
你也可以展开工具调用下拉菜单，查看 Claude 与 SQLite MCP 服务之间请求和响应的详细信息。
输入“yes”继续。接着，Claude 会调用 SQLite MCP 服务中适当的工具，并以表格形式显示 UnderDoc 费用 DB 中“myexpense”表的架构。
通过提问进行支出分析
现在，我们可以询问有关支出的问题。例如，我想查看不同类别和币种的支出分布。提交以下查询。
Show me the total amount of expense by category, by currency
Claude 会在 SQLite MCP 服务中找到合适的工具（本例中为 read_query），并以表格形式列出数据。
Claude 也足够聪明，能注意到有两个相似的类别（“Food”和“food”），并询问你是否要将它们合并。回答“是”，Claude 就会提交另一个查询来合并这两个类别，并重新显示数据。
现在，让我们让 Claude 以图表形式显示数据。提交以下查询。
Show me the result in a multi-line chart
随后，Claude 会生成并运行所需代码，然后显示图表。当你将鼠标悬停在某个类别上时，就会显示各币种的金额。你可以与 Claude 互动来调整图表（例如，更改 y 轴金额的刻度，使其更易于阅读）。
支出涉及多种币种（USD、TWD、JPY、HKD），假设我想将所有支出金额转换为我的本位币，以便统一查看。输入以下查询。
Convert all expense amount to HKD currency
Claude 足够聪明，能够查询网页以获取其他币种兑换为 HKD 的最新汇率，重新运行查询并生成新图表。以下是我得到的结果。
你可以继续让 Claude 微调图表（例如，更改坐标轴、颜色等），或筛选特定时期的支出，并分析支出，而无需掌握任何工具（例如 Metabase）或 SQL 知识！
最后的话
希望你觉得本教程有趣且实用。如果你有任何意见或问题，请随时联系我（[email protected]），我很乐意为你解答！
资源
评论
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。