Zaim API MCP Server
Provides tools for interacting with the Zaim API to manage household account book data, allowing for the retrieval, creation, updating, and deletion of financial records, as well as access to user master data for categories, genres, and accounts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Zaim API MCP Server Record a 1,200 yen lunch today under the food category"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Zaim API MCP Server
Zaimの家計簿データを取得・作成・更新・削除する、Go製のMCPサーバーです。MCPクライアントとはstdioで通信し、Zaim APIへのリクエストにはOAuth 1.0aの署名を付けます。
特徴
認証・ユーザー情報、家計簿、マスターデータを扱う18ツール
公式Go MCP SDK v1.8.0と、Zaim API向けのGo SDK go-zaim v0.1.0を使用
MCP 2026-07-28、2025-11-25、2025-06-18、2025-03-26、2024-11-05に対応
JSON Schemaで入力・出力を検証し、結果を
structuredContentとJSONテキストで返却小数金額やAPI由来の追加フィールドを保持
GoバイナリとDockerによる起動
Related MCP server: Money Lover MCP Server
要件
ソースからビルドする場合はGo 1.26.2以上、Dockerで起動する場合はDockerが必要です。
インストール・起動
ローカルバイナリ
git clone https://github.com/yone-k/zaim-api-mcp.git
cd zaim-api-mcp
go build -o dist/zaim-api-mcp ./cmd/zaim-api-mcp
./dist/zaim-api-mcpGoのbinディレクトリへインストールする場合は、ソース取得後に次を実行します。
go install ./cmd/zaim-api-mcp
zaim-api-mcpサーバーはstdinからMCPメッセージを受け取り、stdoutへ応答します。起動ログはstderrへ出力します。
Docker
docker build -t zaim-api-mcp .
docker run --rm -i \
-e ZAIM_CONSUMER_KEY -e ZAIM_CONSUMER_SECRET \
-e ZAIM_ACCESS_TOKEN -e ZAIM_ACCESS_TOKEN_SECRET \
zaim-api-mcp環境変数を設定したシェルから、Composeでも起動できます。
docker compose build
docker compose run --rm -T zaim-apiauth loginで保存した認証情報をDockerで使う方法は、「Dockerで保存した認証情報を使う」を参照してください。
認証
Zaim APIへのリクエストには、OAuth 1.0aの署名に使う次の4つの値が必要です。
値 | 入手方法 |
Consumer Key・Consumer Secret | Zaim Developersでアプリケーションを登録して発行 |
Access Token・Access Token Secret |
|
4つの値は、auth loginでファイルに保存するか、環境変数で渡します。サーバーは次の基準で認証情報を選びます。
4つの環境変数がすべて設定されていれば、環境変数を使います。
4つとも未設定なら、
auth loginで保存したファイルを使います。一部だけ設定されている場合は、保存したファイルと組み合わせずにエラーにします。
認証情報はツールの実行時に検証するため、未設定でもサーバーの起動とツール一覧の取得はできます。
auth loginで保存する
go installでインストールした場合は、次のコマンドを実行します。dist/にビルドした場合は、./dist/zaim-api-mcp auth loginを実行してください。
zaim-api-mcp auth loginConsumer KeyとConsumer Secretを入力します。環境変数
ZAIM_CONSUMER_KEYとZAIM_CONSUMER_SECRETが設定されていれば、入力は求めません。ブラウザでZaimの認可画面が開くので、アクセスを許可します。ブラウザが開かない場合は、表示されたURLを手動で開いてください。
コマンドがAccess Tokenを取得し、4つの値をファイルに保存します。
保存先は~/.config/zaim-api-mcp/credentials.jsonです。XDG_CONFIG_HOMEを設定している場合は、$XDG_CONFIG_HOME/zaim-api-mcp/credentials.jsonに保存します。ファイルは本人だけが読み書きできる権限(0600)で作成します。
認可後のコールバックはhttp://localhost:8080/callbackで受け取ります。ポートを変える場合は--portを指定してください。5分以内に許可しないと中断します。
保存した認証情報を使う場合、MCPクライアントの設定にenvは不要です。これまで環境変数で設定していた場合は、MCPクライアントの設定から4つのZAIM_*を削除してください。4つとも残っていると環境変数が使われ、一部だけ残っているとエラーになります。
環境変数で渡す
Access TokenとAccess Token Secretを別の方法で取得済みの場合は、4つの値を環境変数で渡せます。
export ZAIM_CONSUMER_KEY=your_consumer_key
export ZAIM_CONSUMER_SECRET=your_consumer_secret
export ZAIM_ACCESS_TOKEN=your_access_token
export ZAIM_ACCESS_TOKEN_SECRET=your_access_token_secretDockerで保存した認証情報を使う
ホストでauth loginを実行してから、保存先のディレクトリを読み取り専用でマウントします。コンテナ内でファイルを読めるよう、--userでホストと同じユーザーIDを指定してください。
docker run --rm -i \
--user "$(id -u):$(id -g)" \
-e XDG_CONFIG_HOME=/config \
-v "$HOME/.config/zaim-api-mcp:/config/zaim-api-mcp:ro" \
zaim-api-mcpMCPクライアント設定
サーバー名は従来のzaim-apiを使います。commandには、ビルドしたGoバイナリの絶対パスを指定してください。
auth loginで認証情報を保存した場合の設定例です。
{
"mcpServers": {
"zaim-api": {
"command": "/absolute/path/to/zaim-api-mcp/dist/zaim-api-mcp"
}
}
}環境変数で渡す場合の設定例です。
{
"mcpServers": {
"zaim-api": {
"command": "/absolute/path/to/zaim-api-mcp/dist/zaim-api-mcp",
"env": {
"ZAIM_CONSUMER_KEY": "your_consumer_key",
"ZAIM_CONSUMER_SECRET": "your_consumer_secret",
"ZAIM_ACCESS_TOKEN": "your_access_token",
"ZAIM_ACCESS_TOKEN_SECRET": "your_access_token_secret"
}
}
}
}Dockerを使う場合の設定例です。
{
"mcpServers": {
"zaim-api": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "ZAIM_CONSUMER_KEY",
"-e", "ZAIM_CONSUMER_SECRET",
"-e", "ZAIM_ACCESS_TOKEN",
"-e", "ZAIM_ACCESS_TOKEN_SECRET",
"zaim-api-mcp"
],
"env": {
"ZAIM_CONSUMER_KEY": "your_consumer_key",
"ZAIM_CONSUMER_SECRET": "your_consumer_secret",
"ZAIM_ACCESS_TOKEN": "your_access_token",
"ZAIM_ACCESS_TOKEN_SECRET": "your_access_token_secret"
}
}
}
}ツール
分類 | ツール | 操作 |
認証 |
| 認証状態の確認 |
ユーザー |
| プロフィール・統計情報の取得 |
家計簿 |
| フィルター・ページ指定で記録を取得 |
家計簿 |
| 支出の作成 |
家計簿 |
| 収入の作成 |
家計簿 |
| 振替の作成 |
家計簿 |
| 記録の更新 |
家計簿 |
| 記録の削除 |
家計簿 |
| 支出の一括作成(最大100件) |
家計簿 |
| 収入の一括作成(最大100件) |
家計簿 |
| 振替の一括作成(最大100件) |
家計簿 |
| 記録の一括更新(最大100件) |
マスター |
| ユーザーカテゴリ一覧 |
マスター |
| ユーザージャンル一覧 |
マスター |
| 口座一覧 |
マスター |
| デフォルトカテゴリ一覧 |
マスター |
| デフォルトジャンル一覧 |
マスター |
| 通貨一覧 |
ツール名・引数・既定値と、成功時のJSON形式は従来どおりです。
記録取得の既定値は
limit=20・page=1です。作成・更新の
amountは正数です。支出の更新には
genre_idが必要です。入力検証・認証・API処理に失敗した場合は
isError=trueを返します。一括処理は
itemsの各要素を単体ツールと同じ引数で受け取り、順番に1回ずつ送信します。失敗した要素があっても残りを続け、要素ごとの結果を返します。isError=trueになるのは、全件が失敗した場合です。dry_run=trueではAPIを呼ばずに検証のみ行います。
対応プロトコル
MCP 2026-07-28のクライアントはserver/discoverとリクエストごとの_metaを使い、旧仕様のクライアントはinitializeで接続します。2024-10-07は対応バージョンに含まれません。
開発・検証
go test ./...
go vet ./...
go build -o dist/zaim-api-mcp ./cmd/zaim-api-mcp単体操作の14ツールの入力と期待する結果を収録した、199件のテストデータで互換性を検証します。API応答にはダミーHTTPサーバーを使います。
プロトコルテストでは実バイナリを起動し、新旧仕様での接続、stdoutとstderrの分離、EOF・SIGINT・SIGTERMによる終了を確認します。キャンセルがHTTP通信まで伝わることも検証します。
Dockerイメージにも同じstdio検証を実行できます。
docker build -t zaim-api-mcp .
ZAIM_MCP_TEST_IMAGE=zaim-api-mcp go test ./internal/mcp -run TestStdioServer -count=1テストは実Zaim APIへ接続しません。実バイナリの検証では、認証情報の環境変数を空にします。ローカルのバイナリを起動するときは、HOMEとXDG_CONFIG_HOMEも一時ディレクトリに向け、保存した認証情報を読まないようにしています。
PR作成・更新時とmainへの更新時には、GitHub Actionsでコードの整形、vet、race検査付きテスト、ビルドを確認します。Dockerでも新旧仕様での接続と終了処理を検証します。
ディレクトリ構成
cmd/zaim-api-mcp/ 起動・終了処理、authサブコマンドの振り分け
internal/auth/ auth loginの認可フロー
internal/config/ 環境変数・保存ファイルからの認証情報の読込、保存、伏字
internal/mcp/ MCPサーバーと契約・プロトコルテスト
internal/mcp/tools/ 18ツール、入出力スキーマ、応答変換
internal/version/ サーバーバージョン
testdata/ 互換性検証用のテストデータと既存ツール定義ライセンス
関連リンク
Available Tools
14 toolszaim_check_auth_statusB
Zaim APIの認証状態をチェックし、アクセストークンの有効性を確認します
Inputs: no named parameters.
zaim_create_incomeC
Zaimに収入記録を作成します
Inputs: amount (required), date (required), category_id (required), to_account_id, +2 more.
zaim_create_paymentC
Zaimに支出記録を作成します
Inputs: amount (required), date (required), category_id (required), genre_id (required), +4 more.
zaim_create_transferB
Zaimに振替記録を作成します(口座間の資金移動)
Inputs: amount (required), date (required), from_account_id (required), to_account_id (required), +1 more.
zaim_delete_money_recordA
Zaimの家計簿記録を削除します。削除は永続的で復元できません。
Inputs: id (required), mode (required).
zaim_get_currenciesB
Zaimで利用可能な通貨一覧を取得します
Inputs: no named parameters.
zaim_get_default_categoriesB
Zaimのデフォルトカテゴリ一覧を取得します(支出または収入)
Inputs: mode (required).
zaim_get_default_genresB
Zaimのデフォルトジャンル一覧を取得します(支出または収入)
Inputs: mode (required).
zaim_get_money_recordsB
Zaim家計簿の支出・収入・振替記録を取得します。日付範囲、カテゴリ、モードでフィルタリング可能です。
Inputs: mode, start_date, end_date, category_id, +2 more.
zaim_get_user_accountsB
Zaimユーザーの口座一覧を取得します
Inputs: no named parameters.
zaim_get_user_categoriesB
Zaimユーザーのカスタムカテゴリ一覧を取得します
Inputs: no named parameters.
zaim_get_user_genresB
Zaimユーザーのカスタムジャンル一覧を取得します
Inputs: no named parameters.
zaim_get_user_infoB
Zaimユーザーの詳細情報(プロフィール、統計情報等)を取得します
Inputs: no named parameters.
zaim_update_money_recordC
Zaimの既存の家計簿記録を更新します
Inputs: id (required), mode (required), amount, date, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Every tool has a clearly distinct purpose with no ambiguity. Tools are well-separated by resource (e.g., money records, categories, user info) and action (e.g., create, get, update, delete). For example, zaim_create_income, zaim_create_payment, and zaim_create_transfer handle different types of money records, while get tools target specific data sets like currencies or accounts.
All tool names follow a consistent verb_noun pattern with the prefix 'zaim_', such as zaim_create_income, zaim_get_currencies, and zaim_update_money_record. This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming style or structure.
With 14 tools, the count is well-scoped for a personal finance API server. Each tool earns its place by covering essential operations like CRUD for money records, retrieval of metadata (currencies, categories), and user management, without being excessive or too sparse for the domain.
The tool surface provides complete CRUD/lifecycle coverage for the Zaim API domain. It includes creation, retrieval, update, and deletion for money records, along with supporting operations for authentication, user info, accounts, and metadata (currencies, categories, genres). No obvious gaps exist; agents can perform full workflows without dead ends.
Maintenance
Related MCP Connectors
Track expenses, budgets, balances, transfers, and multi-currency reports with OAuth-secured tools.
Personal finance for AI agents: accounts, budgets, goals, 9-strategy debt payoff, reports. OAuth 2.1
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Document sharing, invoicing, and personal finance platform. 15+ AI tools via OAuth 2.1.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with YNAB budgets through natural language. Supports managing accounts, categories, transactions, and budget months with 21 tools for comprehensive budget operations.-
- AlicenseAqualityDmaintenanceEnables AI assistants to query and manage personal finance data through the unofficial Money Lover REST API. It provides 27 tools covering authentication, wallets, categories, transactions, events, debts, and static configuration with both read and write capabilities.33ISC
- AlicenseAqualityCmaintenanceEnables AI agents to access accounts, balances, transactions and reports, manage monthly budgets, planned operations and debts, categorize spending, and safely create or edit records through the official ZenMoney API.2292 npm2MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants and MCP clients to access and manage personal finance data through LunchMoney’s API, including transactions, categories, tags, budgets, recurring items, accounts, crypto, and balance history. It supports full CRUD, filtering, bulk operations, attachments, and token-efficient responses for automated financial insights.41 npm-