Skip to main content
Glama
yone-k

Zaim API MCP Server

by yone-k
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Zaim API MCP Server

English README

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 ワークフロー

  1. 機能ごとにブランチを作成

  2. TDD（テスト駆動開発）で実装

  3. すべてのテストが通ることを確認

  4. プルリクエストを作成

コミットメッセージ規約

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デーモンが起動しているか確認

  • 環境変数が正しく渡されているか確認

  • ログで詳細なエラーメッセージを確認

貢献

  1. リポジトリをフォーク

  2. フィーチャーブランチを作成 (git checkout -b feat/amazing-feature)

  3. 変更をコミット (git commit -m 'feat: 素晴らしい機能を追加')

  4. ブランチをプッシュ (git push origin feat/amazing-feature)

  5. プルリクエストを作成

ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

関連リンク

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yone-k/zaim-api-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server