Zaim API MCP Server
Zaim APIとの連携を可能にするMCP (Model Context Protocol) サーバーです。OAuth 1.0a認証を使用してZaimの家計簿データの取得・操作を行います。
特徴
- Zaim API(OAuth 1.0a)との完全な統合
- 14個の包括的なツールセット
- 家計簿データの取得・作成・更新・削除
- マスターデータ(カテゴリ、ジャンル、口座、通貨)の取得
- TypeScriptベースの型安全な実装
- Zodスキーマによる厳密なバリデーション
- 包括的なテストカバレッジ(128テスト)
- Dockerサポート
実装済みツール
認証・ユーザー情報
zaim_check_auth_status- 認証状態の確認zaim_get_user_info- ユーザー情報の取得
家計簿データ操作
zaim_get_money_records- 家計簿記録の取得(フィルタリング・ページネーション対応)zaim_create_payment- 支出記録の作成zaim_create_income- 収入記録の作成zaim_create_transfer- 振替記録の作成zaim_update_money_record- 既存記録の更新zaim_delete_money_record- 記録の削除
マスターデータ取得
zaim_get_user_categories- ユーザーカテゴリ一覧zaim_get_user_genres- ユーザージャンル一覧zaim_get_user_accounts- ユーザー口座一覧zaim_get_default_categories- デフォルトカテゴリ一覧zaim_get_default_genres- デフォルトジャンル一覧zaim_get_currencies- 利用可能通貨一覧
要件
- Docker(推奨)
- Node.js 22+(ローカル開発時)
- Zaim APIのOAuth認証情報
- Consumer Key
- Consumer Secret
- Access Token
- Access Token Secret
環境変数設定
# 必須:Zaim API認証情報
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を使用(推奨)
# リポジトリをクローン
git clone https://github.com/yone-k/zaim-api-mcp.git
cd zaim-api-mcp
# Dockerイメージをビルド
docker build -t zaim-api-mcp .
ローカル開発
# 依存関係をインストール
npm install
# 開発モードで開始
npm run dev
# テスト実行
npm test
# ビルド
npm run build
Claude Desktop設定
1. 設定ファイルの場所
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Docker設定(推奨)
{
"mcpServers": {
"zaim-api": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "ZAIM_CONSUMER_KEY=your_consumer_key",
"-e", "ZAIM_CONSUMER_SECRET=your_consumer_secret",
"-e", "ZAIM_ACCESS_TOKEN=your_access_token",
"-e", "ZAIM_ACCESS_TOKEN_SECRET=your_access_token_secret",
"zaim-api-mcp"
]
}
}
}
3. ローカルビルド設定
{
"mcpServers": {
"zaim-api": {
"command": "node",
"args": ["/path/to/zaim-api-mcp/dist/index.js"],
"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"
}
}
}
}
使用例
認証状態の確認
zaim_check_auth_status を使って認証が正しく設定されているか確認してください
家計簿データの取得
zaim_get_money_records を使って、2024年1月の支出記録を取得してください
支出の記録
zaim_create_payment を使って、本日1,500円の昼食代を食費カテゴリで記録してください
カテゴリ一覧の取得
zaim_get_user_categories を使って利用可能なカテゴリ一覧を表示してください
API設定
config/zaim-config.jsonで詳細な設定が可能です:
- APIタイムアウト設定
- レート制限設定
- キャッシュ設定
- ログレベル設定
プロジェクト構造
zaim-api-mcp/
├── src/
│ ├── core/ # MCPサーバーコア機能
│ │ ├── tool-handler.ts
│ │ └── zaim-api-client.ts
│ ├── tools/ # ツール実装
│ │ ├── auth/ # 認証関連ツール
│ │ ├── money/ # 家計簿データツール
│ │ ├── master/ # マスターデータツール
│ │ └── registry.ts # ツール登録
│ ├── types/ # 型定義
│ ├── utils/ # ユーティリティ
│ └── index.ts # エントリーポイント
├── tests/ # テストファイル
├── config/ # 設定ファイル
└── docker-compose.yml # Docker設定
開発ガイド
Git ワークフロー
- 機能ごとにブランチを作成
- TDD(テスト駆動開発)で実装
- すべてのテストが通ることを確認
- プルリクエストを作成
コミットメッセージ規約
feat: 新機能の追加
fix: バグ修正
docs: ドキュメントの変更
refactor: リファクタリング
test: テストの追加・修正
chore: ビルドプロセスやツールの変更
利用可能なスクリプト
npm run build # TypeScriptビルド
npm run start # 本番サーバー起動
npm run dev # 開発サーバー起動
npm run lint # ESLint実行
npm run typecheck # 型チェック
npm test # テスト実行
npm run test:watch # テスト監視モード
npm run test:coverage # カバレッジレポート
npm run docker:build # Dockerイメージビルド
npm run docker:run # Dockerコンテナ実行
npm run docker:dev # Docker Compose起動
トラブルシューティング
認証エラー
- 環境変数が正しく設定されているか確認
- Zaim開発者サイトでアプリケーションの設定を確認
- アクセストークンの有効期限を確認
Docker関連
- Dockerデーモンが起動しているか確認
- 環境変数が正しく渡されているか確認
- ログで詳細なエラーメッセージを確認
貢献
- リポジトリをフォーク
- フィーチャーブランチを作成 (
git checkout -b feat/amazing-feature) - 変更をコミット (
git commit -m 'feat: 素晴らしい機能を追加') - ブランチをプッシュ (
git push origin feat/amazing-feature) - プルリクエストを作成
ライセンス
MITライセンス - 詳細はLICENSEファイルを参照してください。
