Zaim API MCP Server

English README

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による起動

要件

ソースからビルドする場合は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-mcp

Goの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-api

auth loginで保存した認証情報をDockerで使う方法は、「Dockerで保存した認証情報を使う」を参照してください。

認証

Zaim APIへのリクエストには、OAuth 1.0aの署名に使う次の4つの値が必要です。

4つの値は、auth loginでファイルに保存するか、環境変数で渡します。サーバーは次の基準で認証情報を選びます。

• 4つの環境変数がすべて設定されていれば、環境変数を使います。
• 4つとも未設定なら、auth loginで保存したファイルを使います。
• 一部だけ設定されている場合は、保存したファイルと組み合わせずにエラーにします。

認証情報はツールの実行時に検証するため、未設定でもサーバーの起動とツール一覧の取得はできます。

auth loginで保存する

go installでインストールした場合は、次のコマンドを実行します。dist/にビルドした場合は、./dist/zaim-api-mcp auth loginを実行してください。

zaim-api-mcp auth login

1. Consumer KeyとConsumer Secretを入力します。環境変数ZAIM_CONSUMER_KEYとZAIM_CONSUMER_SECRETが設定されていれば、入力は求めません。
2. ブラウザでZaimの認可画面が開くので、アクセスを許可します。ブラウザが開かない場合は、表示されたURLを手動で開いてください。
3. コマンドが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_secret

Dockerで保存した認証情報を使う

ホストで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-mcp

MCPクライアント設定

サーバー名は従来の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"
      }
    }
  }
}

ツール

ツール名・引数・既定値と、成功時の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/              互換性検証用のテストデータと既存ツール定義

ライセンス

MIT

関連リンク

• Zaim API
• MCP仕様
• 公式Go MCP SDK