Provides integration with freee会計 (freee accounting) API, allowing access to accounting data including companies, account items, partners, sections, items, tags, deals, and trial balances. Enables creating and managing transactions, partners, and account items.
📊 freee会計 MCP Server
freee会計APIと連携するModel Context Protocol (MCP) Serverです。
🎯 概要
このプロジェクトは、freee会計APIを通じて会計データにアクセスし、AI アシスタントが会計業務を支援できるようにするMCPサーバーを提供します。
⚡ 機能
📄 Resources
- 事業所情報の取得 (
companies://list
,companies://current
) - 勘定科目一覧の取得 (
account-items://list
) - 取引先情報の取得 (
partners://list
) - 部門情報の取得 (
sections://list
) - 品目情報の取得 (
items://list
) - メモタグ情報の取得 (
tags://list
) - 取引データの取得 (
deals://list
) - 試算表データの取得 (
trial-balance://current
)
🔧 Tools
- 🔐 認証管理 (
generate-auth-url
,exchange-auth-code
,check-auth-status
) - ✅ 接続テスト (
test-connection
) - 💰 取引管理 (
create-deal
,update-deal
,get-deals
) - 🏢 取引先の作成 (
create-partner
) - 📊 勘定科目の作成 (
create-account-item
) - 📈 システム監視 (
get-rate-limit-info
,get-logs
,get-metrics
,get-health
) - 🗄️ キャッシュ管理 (
get-cache-stats
,clear-cache
)
💡 Prompts
- 🚀 セットアップガイド (
setup-guide
) - ✏️ 取引入力支援 (
transaction-entry
) - 📅 月次決算チェックリスト (
monthly-closing
) - 📊 試算表分析ガイド (
trial-balance-analysis
)
🏗️ プロジェクト構成
✨ 特徴
- 🔐 OAuth 2.0認証: freee公式認証フローに完全準拠
- 🏢 事業所ID設定: 環境変数で事業所IDを設定可能(デフォルト: 123456)
- 💰 包括的な取引管理: 取引の作成・更新・一覧取得をサポート
- 🛡️ 型安全: TypeScriptによる完全な型定義
- 📦 モノレポ構成: 共通ライブラリとアプリケーションの分離
- 🔄 MCP準拠: Model Context Protocolの仕様に完全準拠
- ⚡ レート制限対応: 自動的なレート制限管理とリトライ機能
- 📊 包括的なログ: レベル別ログ機能と運用監視
- 🚨 エラーハンドリング: 詳細なエラー情報とリトライ可能性の判定
- 💾 認証情報永続化: トークンの自動保存・復元機能
- 🚀 高性能キャッシュ: メモリベースキャッシュによる高速レスポンス
- 🔒 セキュリティ強化: トークン暗号化、セキュリティ監査、入力値検証
- 📈 監視・メトリクス: リアルタイム監視、ヘルスチェック、アラート機能
- 🏭 プロダクションレディ: 企業レベルでの運用に対応
🚀 セットアップ
📋 前提条件
Node.js 18.0.0以上
npm 9.0.0以上
📦 インストール
⚙️ 環境変数設定
.env
ファイルを作成し、以下の環境変数を設定してください:
🔐 OAuth 2.0認証
⚠️ 注意:
- OAuth認証では事業所選択機能を制御できます。
- 事業所選択を有効にすると、認証時に特定の事業所を選択してアクセスを制限できます。
- 事業所選択を無効にすると、ユーザーが所属する全ての事業所にアクセス可能になります。
🏢 事業所IDの取得方法
事業所IDを取得する方法は複数あります:
- 🌐 freee Web版から取得
- freee Web版にログインし、設定画面やURLから事業所IDを確認できます
- ブラウザのアドレスバーで
https://secure.freee.co.jp/companies/XXXXXX
のXXXXXXが事業所IDです
- 🔌 API経由で取得
- 認証後、
get-companies
ツールを使用して利用可能な事業所一覧を取得できます - レスポンスの
id
フィールドが事業所IDになります
- 認証後、
- 🤖 Claude Code経由で取得
- Claude Codeで「利用可能な事業所を教えてください」とリクエストすることで確認できます
⚠️ 重要な免責事項
🚨 本MCPサーバーについて
- 本MCPサーバーは非公式のものです
- freee株式会社によって開発・サポートされているものではありません
- 本ソフトウェアの使用によって生じた一切の損害について、開発者は責任を負いません
- 本番環境での使用は自己責任でお願いします
- データの正確性や完全性について保証するものではありません
📦 インストール方法
🚀 オンラインインストール(推奨)
NPMからのインストール:
npxを使用した直接実行:
🔧 ローカル開発版のインストール
開発者向けまたはローカル環境での使用:
🤖 Claude Codeでの使用方法
1️⃣ 設定の確認
2️⃣ Claude Codeでの使用
MCPサーバーがインストールされると、Claude Codeで以下のリソースとツールが利用できます:
- 📊 会計データの取得: 取引、勘定科目、取引先などの情報
- ✏️ 取引の作成・更新: 新規取引の入力や既存取引の修正
- 📈 試算表の分析: 月次・年次の財務データの分析
- 🔐 認証管理: freee APIへの認証とアクセス管理
3️⃣ 使用例
Claude Codeで以下のようにMCPサーバーを活用できます:
🔧 従来の使用方法
🔐 認証の設定
OAuth認証の場合
- freeeアプリケーションの作成
- freeeアプリストアの開発者向けアプリ一覧画面にアクセス
- 「新規追加」をクリックしてアプリケーションを作成
- アプリ名と概要を入力
- Client IDとClient Secretを取得
- 環境変数を設定
- MCP Serverを起動
- OAuth認証フローの実行a. 認証URLを生成:b. 生成されたURLにブラウザでアクセス:
- freeeアカウントでログイン
- 事業所を選択(enable_company_selection=trueの場合)
- アプリケーションのアクセス権限を確認
- 「許可する」をクリック
c. 認証コードを取得:
- リダイレクトURLのcodeパラメータから認証コードを取得
d. 認証コードをアクセストークンに交換:
- 認証状態の確認
📖 基本的な使用例
🏗️ アーキテクチャ
🔧 レイヤー構成
このプロジェクトは、クリーンアーキテクチャの原則に基づいて設計されています:
🔧 インフラ層の主要コンポーネント
🌐 FreeeApiClient
- freee APIとの通信を担当する統一インターフェース
- レート制限、リトライ、キャッシュ機能を内蔵
- デバッグ機能とログ機能を統合
🔄 ApiResponseMapper
- freee APIレスポンスの標準化とマッピング
- 型安全なデータ変換
- ページネーション情報の抽出
🔍 DebugInterceptor
- HTTP リクエスト/レスポンスのデバッグ出力
- MCP Inspector対応
- 機密情報のマスキング機能
📊 LoggerSetup
- 環境別ログ設定の管理
- プロファイルベースの設定切り替え
- 構造化ログとファイル出力
🔌 依存性注入
InversifyJSを使用したDIコンテナにより、各レイヤー間の疎結合を実現:
🚨 エラーハンドリング
Result型パターンを採用し、型安全なエラーハンドリングを実現:
🛠️ 開発
📋 利用可能なスクリプト
npm run build
- 全パッケージのビルドnpm run dev
- 開発モードでの実行npm run test
- テストの実行npm run lint
- リントの実行npm run type-check
- 型チェックの実行npm run format
- コードフォーマットの実行npm run debug
- MCP Inspector を使用したデバッグ(開発版)npm run debug:build
- MCP Inspector を使用したデバッグ(ビルド版)npm run inspect
- MCP Inspector を使用したインタラクティブテスト(開発版)npm run inspect:build
- MCP Inspector を使用したインタラクティブテスト(ビルド版)
🏗️ 開発環境
このプロジェクトはmonorepo構成でTurborepoを使用しています。各パッケージは独立して開発・テストできます。
📦 ES Module対応
プロジェクトは完全にES Moduleに対応しており、以下の特徴があります:
- 全パッケージで
"type": "module"
を設定 - TypeScriptからES Moduleへの自動変換
- 相対インポートの自動修正(
.js
拡張子の追加) - Node.js 18+での最適化されたパフォーマンス
🔧 ビルドプロセス
- TypeScript コンパイル: ソースコードをES Moduleとしてコンパイル
- インポート修正: 相対インポートに
.js
拡張子を自動追加 - 型定義生成:
.d.ts
ファイルの生成 - 依存関係解決: パッケージ間の依存関係を自動解決
🔍 デバッグ
MCP Inspector を使用したデバッグ
MCP Inspector は、MCPサーバーをインタラクティブにテスト・デバッグするためのツールです。
🚀 基本的な使用方法
🛠️ MCP Inspector の機能
- 📄 Resources タブ: 利用可能なリソースの一覧表示とテスト
- 💡 Prompts タブ: プロンプトテンプレートの表示とテスト
- 🔧 Tools タブ: ツールの一覧表示と実行テスト
- 📋 Notifications ペイン: サーバーからのログと通知の表示
🔄 デバッグワークフロー
- 開発開始
- ブラウザで表示されたURL(http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=...)にアクセス
- サーバーとの基本接続を確認
- 機能ネゴシエーションをチェック
- HTTPリクエスト/レスポンスのデバッグデバッグモードでは以下の情報が表示されます:
- 🔐 OAuth認証リクエスト/レスポンス(機密情報はマスク)
- 📡 freee APIリクエスト/レスポンス(アクセストークンはマスク)
- ❌ エラー詳細情報
- Inspector GUI での操作Server Connection Pane(サーバー接続設定):
- Transport:
stdio
を選択(デフォルト) - Command:
tsx
またはnode
- Arguments:
- 開発版:
apps/freee-accounting/src/index.ts
- ビルド版:
apps/freee-accounting/dist/index.js
- 開発版:
- Environment Variables: 必要に応じて環境変数を設定
Resources タブでのテスト:
companies://list
- 事業所一覧の取得companies://current
- 現在の事業所情報account-items://list
- 勘定科目一覧partners://list
- 取引先一覧deals://list
- 取引データ一覧trial-balance://current
- 試算表データ
Tools タブでのテスト:
generate-auth-url
- OAuth認証URL生成(引数不要)check-auth-status
- 認証状態確認(引数不要)test-connection
- 接続テスト(引数不要)get-health
- ヘルスチェック(引数不要)create-deal
- 取引作成(JSON形式で取引データを入力)create-partner
- 取引先作成(JSON形式で取引先データを入力)
Prompts タブでのテスト:
setup-guide
- セットアップガイド(引数不要)transaction-entry
- 取引入力支援(引数不要)monthly-closing
- 月次決算チェックリスト(引数不要)trial-balance-analysis
- 試算表分析ガイド(引数不要)
- Transport:
- 反復テスト
- サーバーコードを変更
- サーバーを再ビルド
- Inspector を再接続
- 影響を受ける機能をテスト
- Notifications ペインでメッセージを監視
- エッジケースのテスト
- 無効な入力値でのツール実行
- 不足しているプロンプト引数
- 並行操作のテスト
- エラーハンドリングとエラーレスポンスの確認
⚙️ 環境変数の設定
デバッグ時は、.env
ファイルに以下の環境変数を設定してください:
🧪 具体的なテスト例
1. 🔐 OAuth認証フローのテスト:
2. 📊 基本データ取得のテスト:
3. 💰 取引作成のテスト:
4. 📈 システム監視のテスト:
🔧 トラブルシューティング
- 🔌 接続エラー: 環境変数が正しく設定されているか確認
- 🔐 認証エラー: freee APIの認証情報が有効か確認
- ⚡ レート制限: API呼び出し頻度を調整
🚀 公開・配布について
NPMパッケージとして公開
このMCPサーバーは@tsurutan/freee-accounting-mcpとしてNPMに公開されており、世界中の開発者が簡単にインストールできます。
GitHub Actions による自動化
- CI/CD パイプライン: コードのプッシュ時に自動テスト・ビルド
- 自動公開: タグ作成時にNPMへの自動公開
- 品質保証: ESLint、TypeScriptチェック、テスト実行
公開手順
🎯 プロジェクト状況
🎉 プロジェクト完了・公開済み!
freee会計 MCP Serverは、5つのフェーズを経て完全に実装され、NPMで公開されているプロダクションレディな状態に到達しました:
- Phase 1-2: 基本機能・OAuth認証・基本リソース・ツール実装 ✅
- Phase 3: 残りのリソース・ツール・Prompts・認証情報永続化 ✅
- Phase 4: レート制限対応・エラーハンドリング強化・ログ機能・テスト実装 ✅
- Phase 5: パフォーマンス最適化・セキュリティ強化・監視機能・ドキュメント充実 ✅
- Phase 6: NPM公開・CI/CD・配布自動化 ✅
🚀 実装済み機能
- 📄 8種類のResources: 事業所、勘定科目、取引先、部門、品目、メモタグ、取引、試算表
- 🔧 12種類のTools: 認証、CRUD操作、システム監視、キャッシュ管理
- 💡 4種類のPrompts: セットアップ、取引入力支援、月次決算、試算表分析
- 🏭 企業レベルの運用機能: 監視、メトリクス、セキュリティ、パフォーマンス最適化
- 📦 パッケージ配布: NPM公開、自動CI/CD、オンラインインストール対応
📄 ライセンス
MIT License
🤝 貢献
プルリクエストやイシューの報告を歓迎します。詳細はdocs/development/
配下の規約をご確認ください。
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables AI assistants to access and manage accounting data through the freee accounting API, supporting operations like transaction management, financial analysis, and account item management.
Related MCP Servers
- AsecurityAlicenseAqualityAllows AI assistants to list tables, read data, and execute SQL queries through a controlled interface, making database exploration and analysis safer and more structured.Last updated -1580PythonMIT License
- AsecurityFlicenseAqualityA server that provides advanced mathematical and financial calculation capabilities for AI code assistants, enabling them to perform complex calculations like symbolic calculus, numerical methods, and financial analysis without implementing algorithms directly.Last updated -181JavaScript
- -securityFlicense-qualityEnables AI assistants to interact with Metabase, providing access to dashboards, questions, databases, and tools for executing queries and viewing data through natural language.Last updated -JavaScript
- -securityFlicense-qualityEnables AI assistants like Claude Desktop, Claude Code, and Cursor to interact directly with Flatfile data through 100+ API endpoints for viewing, managing, and manipulating sheets, workbooks, records, and spaces.Last updated -70TypeScript