UnderDoc Tutorial - Expense Analytics using GenAI and MCP server for SQLite DB について
SQLiteの支出データを題材に、レシートや請求書の画像から構造化データを抽出し、Claude Desktopで自然言語分析する手順を紹介するチュートリアルです。UnderDoc、SQLite、MCPを組み合わせる方法を学ぶ人向けです。
主な機能
- 01レシートや請求書画像から支出データを抽出
- 02構造化した記録をSQLiteに保存
- 03Claude 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 サーバーを使い、LLM と自然言語でチャットしながら経費分析を行う方法について説明します。
このチュートリアルでは GenAI（Claude Desktop）と SQLite 用 MCP サーバーを使用します。データベースには UnderDoc の経費レコードがすでに登録されていることを前提とします。前のチュートリアルの「データを抽出して DB に保存する」のセクションまで進めてください（Metabase に関する残りのセクションはスキップしてください）。MCP サーバーの動作を手早く確認したい場合は、サンプルの経費レコード 20 件が登録された SQLite DB をこちらからダウンロードすることもできます。
このチュートリアルを実行するには、以下が必要です。
- MacOS を搭載したノートパソコンまたはデスクトップパソコン
- uv（SQLite MCP サーバーの実行に使用する Python ランタイムおよびパッケージマネージャー）
- git（MCP サーバーのソースコードを github からクローンするため）
- Claude Desktop（このチュートリアルで使用する、MCP サーバーに対応した GenAI アプリ）
- Sqlite DB
前のチュートリアルをまだ実施していない読者のために、参照しやすいよう手順をこちらに再掲します。SQLite DB の準備ができている場合は、「自然言語を使った経費分析」のセクションに進んでください。
概要
このチュートリアルでは、さまざまなタスクに次のコンポーネントを使用します。
- レシート／請求書／納品書の画像からデータを抽出する UnderDoc
- Python のランタイムを管理し、MCP サーバーを実行する uv
- 抽出したデータを保存する SQLite
- MCP サーバーと LLM を使用して経費を分析する Claude Desktop for Mac
MCP とは
MCP（Model Context Protocol）について解説する記事は数多くあるため、ここでは詳しく説明しません。簡単に言うと、MCP は LLM がユーザーの質問に回答するために必要なさまざまなリソースやツールとやり取りするための標準化された方法を提供します。
Claude desktop や Cursor IDE など、MCP サーバーに対応したツールはすでに数多くあります。OpenAI や Google など、ほかの多くの生成 AI プロバイダーも、自社のサービスで MCP に対応することを発表しています。
GitHub のオープンソース MCP リポジトリには、参照サーバーの一覧があります。このチュートリアルでは、SQLite DBとの連携用サーバーを使用します。
前提条件
UnderDoc API キーを取得する
このチュートリアルの重要な手順は、画像から経費情報（店舗名、金額、通貨、推定カテゴリなど）を抽出し、分析用にデータベースへ保存できる構造化データにすることです。この作業には、コスト効率の高い（無料枠のある）プラットフォームである UnderDoc を使用します。このツールは、多言語の画像にも適しています。
UnderDoc の使い方は簡単です。開発者ポータルにサインアップして、API キーを取得するだけです。
ステップ 1：サインアップ
まず、UnderDoc Developer Portalのサインアップページにアクセスします。
メールアドレスとパスワードを入力し、「Sign Up」を確定します。
サインアップが完了すると、メールが届きます。ログインする前に、メールアドレスを確認する必要があります。
ステップ 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 DB の初期化（任意）
抽出した経費データを保存するために、空の SQLite DB ファイルが必要です。このリポジトリにはすでにファイル（metabase-data/underdoc.db）が用意されています。新しく初期化する場合は、次のコマンドを実行してください。
sqlite3 metabase-data/underdoc.db
経費画像を receipt-images フォルダーにコピーする
スクリプトは receipt-images フォルダー内のすべての画像を処理します。用意されているサンプル画像を使うか、分析用にご自身の画像をフォルダーにコピーしてください。
ここまでこのチュートリアルに沿って進めていただき、本当にありがとうございます！画像から DB へデータを抽出する準備が整いました。
データを抽出して DB に保存する
スクリプトを実行する前に、UnderDoc API キーの環境変数を設定してください。スクリプトはこのキーを使って UnderDoc とやり取りします。
export UNDERDOC_API_KEY=<your_api_key>
環境の設定が完了したら、次のコマンドを実行するだけでデータを DB に抽出できます。
python main.py
このスクリプトは UnderDoc Python SDK を使って UnderDoc の Document Understanding API とやり取りし、返された構造化データを取得してから SQLite DB に保存します。お使いのノートパソコンのハードウェアによっては、複数の画像を並列に抽出しようとします。
スクリプトの実行にはしばらく時間がかかります。正常に完了すると、次のような出力が表示されます。
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 DB 内のデータを確認するには、次のコマンドを実行してください。
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 をダウンロードしてインストールしてください。その後、必要に応じてアカウントを登録してください。
リファレンス MCP サーバーのソースを GitHub からクローンする
執筆時点では、SQLite DB 用のリファレンス MCP サーバーを使用するには、GitHub リポジトリからソースコードをクローンする必要があります。
git clone https://github.com/modelcontextprotocol/servers.git
クローンすると、SQLite 用 MCP サーバーのソースはサブフォルダー「servers/src/sqlite」にあります。MCP サーバーの機能とインストール手順については、README ファイルを参照してください。
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 サーバーをインストール済みの場合は、「mcpServers」セクションに「sqlite」の部分を追加するだけでかまいません。
次のプレースホルダーを置き換えてください。
- <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 icon」をクリックします。
ダイアログボックスが表示され、設定済みの MCP サーバーが提供する、LLM が呼び出せる MCP ツールの一覧が表示されます。次のスクリーンショットはその例です。
SQLite サーバーが提供するツールのうち、2 つを強調表示しました。これらは、LLM が SQLite DB から情報やデータを取得するために使用できる関数呼び出しです。MCP サーバーの設定に UnderDoc DB ファイルが含まれているため、Claude は expense テーブルのスキーマとデータを表示できます。SQLite MCP サーバーが提供するツールの全一覧はこちらで確認できます。このダイアログボックスにツールが表示されていれば、SQLite MCP サーバーが Claude に正常にインストールされたことを意味します。
スクリーンショットには、私が「filesystem」リファレンスサーバーもインストールしたため、ほかのツールも表示されています。
UnderDoc Expense（SQLite）DB の概要
まず、次のクエリを使って、Claude に SQLite DB を確認してもらいましょう。
Show me the tables in the sqlite db
クエリを送信すると、Claude は質問に答えるために SQLite MCP サーバーの「list_tables」ツールを使用できると判断しました。安全のため、ツールを実行する前に許可を求めます。
「Allow for this chat」をクリックして、Claude にツールの実行を許可します。
Claude はツールを実行し、「myexpense」というテーブルが 1 つ見つかったと回答し、その構造を説明するかどうかを尋ねます。
ツール呼び出しのドロップダウンを展開すると、Claude と SQLite MCP サーバー間のリクエストとレスポンスの詳細も確認できます。
「yes」と入力して続行します。すると Claude は SQLite MCP サーバーで適切なツールを呼び出し、UnderDoc expense DB 内の「myexpense」テーブルのスキーマを表形式で表示します。
質問して経費を分析する
これで、経費について質問できるようになりました。たとえば、経費のカテゴリ別および通貨別の内訳を確認したいとします。次のクエリを送信してください。
Show me the total amount of expense by category, by currency
Claude は SQLite MCP サーバーの適切なツール（この場合は read_query）を特定し、データを表形式で一覧表示します。
Claude は、「Food」と「food」という類似したカテゴリが 2 つあることにも気づき、それらを統合するかどうか尋ねてくれます。「はい」と答えると、Claude は 2 つのカテゴリを統合するクエリを再度送信し、データを表示し直します。
次に、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 サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。