Skip to content
Back to search

freee-mcp-marketplace

MarketplaceWorks with Claude CodeGitHub

freee 公式の Claude Code プラグインのマーケットプレイス

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 17 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/freee/freee-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/freee/freee-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/freee-freee-mcp/badge.svg)](/listings/freee-freee-mcp)

HTML

<a href="/listings/freee-freee-mcp"><img src="/api/listings/freee-freee-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines
  1. {
  2. "name": "freee-mcp-marketplace",
  3. "owner": {
  4. "name": "freee"
  5. },
  6. "description": "freee 公式の Claude Code プラグインのマーケットプレイス",
  7. "plugins": [
  8. {
  9. "name": "freee-mcp",
  10. "source": {
  11. "source": "github",
  12. "repo": "freee/freee-mcp",
  13. "ref": "claude-plugin"
  14. },
  15. "version": "0.38.2",
  16. "description": "freee API を MCP 経由で操作するためのスキル。詳細なAPIリファレンス(パラメータ、リクエストボディ、レスポンス情報含む)と、freee-mcp を使用した API 呼び出しガイドを提供。OAuth 認証とトークン管理を自動化し、経費申請、会計データ取得、人事情報管理など、freee の様々な機能を利用可能。"
  17. }
  18. ]
  19. }
README.md · README · 411 lines
  1. # freee-mcp
  2. freee会計、人事労務、請求書、工数管理、販売、IT管理、固定資産、債権管理、業務委託管理、サーベイ、開業、人事評価、申告、サイン(電子契約)を AI Agent から操作できるようにする freee 公式の MCP サーバーと Agent Skills です。
  3. - MCP サーバー: freee API の呼び出し・認証・リクエスト検証を担当
  4. - Agent Skills: API リファレンスと操作レシピを AI Agent のコンテキストに注入し、正確な API 利用をガイド
  5. [![npm version](https://badge.fury.io/js/freee-mcp.svg)](https://www.npmjs.com/package/freee-mcp)
  6. ## 特徴
  7. - 複数 API 対応: 会計・人事労務・請求書・工数管理・販売・IT管理・固定資産・債権管理・業務委託管理・サーベイ・開業・人事評価・申告の13個の freee API をサポート
  8. - 対応操作数: <!-- API-STATS-TOTAL-START -->608<!-- API-STATS-TOTAL-END --> 操作(サイン(電子契約)含む、`scripts/generate-references.ts` が自動更新)
  9. - 利用条件: サーベイ・開業・人事評価・申告は、対応する接続環境、OAuth クライアント、契約プラン、利用者権限が必要
  10. - サイン(電子契約)対応: freee サインの文書管理 API を専用コマンド(`freee-sign-mcp`)でサポート
  11. - OAuth 2.0 + PKCE: セキュアな認証フロー、トークン自動更新
  12. - 複数事業所対応: 事業所の動的切り替えが可能
  13. ## Agent Skills と MCP の通信の流れ
  14. Agent Skills(API リファレンス・操作レシピ)と MCP サーバー(API 呼び出し)を組み合わせて利用します。
  15. ```mermaid
  16. sequenceDiagram
  17. participant User as ユーザー
  18. participant Agent as AI Agent
  19. participant Skill as Agent Skills<br/>(API リファレンス・操作レシピ)
  20. participant MCP as MCP サーバー
  21. participant API as freee API
  22. User->>Agent: リクエスト<br/>「取引一覧を取得して」
  23. Note over Agent,Skill: 1. Agent Skills からリファレンスを取得
  24. Agent->>Skill: freee-api-skill 呼び出し
  25. Skill-->>Agent: API リファレンス注入<br/>(エンドポイント、パラメータ仕様)
  26. Note over Agent,MCP: 2. MCP Tool で API を実行
  27. Agent->>MCP: freee_api_get 呼び出し<br/>path: /api/1/deals
  28. MCP->>MCP: OpenAPI スキーマで検証
  29. MCP->>MCP: 認証トークン付与
  30. Note over MCP,API: 3. freee API への通信
  31. MCP->>API: GET /api/1/deals<br/>Authorization: Bearer xxx
  32. API-->>MCP: JSON レスポンス
  33. MCP-->>Agent: 取引データ
  34. Agent-->>User: 結果を整形して表示
  35. ```
  36. この仕組みにより:
  37. - Agent Skills: 必要な API リファレンスや操作レシピを段階的にコンテキストに注入(コンテキスト効率化)
  38. - MCP: 認証・リクエスト検証・API 呼び出しを担当
  39. ## クイックスタート
  40. ### 方法 1: Remote MCP で接続する(推奨)
  41. freee が提供する Remote MCP サーバーに接続する方法です。ローカルでのセットアップが不要で、すぐに利用を開始できます。
  42. Claude 及び Claude Desktop では「カスタマイズ」より「カスタムコネクタを追加」を開き、以下を設定してください。
  43. - 名前: `freee`
  44. - URL: `https://mcp.freee.co.jp/mcp`
  45. > ⚠️ freee 公式以外の URL を入力しないようにご注意ください。
  46. <img src="docs/images/claude-desktop-custom-connector.png" width="600" alt="Claude Desktop でカスタムコネクタを追加">
  47. その他の AI ツールでは、それぞれの案内に従って Remote MCP サーバーを追加してください。
  48. ### 方法 2: ローカルで MCP サーバーを起動する
  49. freee アプリケーションを自分で登録し、ローカルで MCP サーバーを起動する方法です。手順は「[ローカル MCP を使う場合](#ローカル-mcp-を使う場合)」をご覧ください。
  50. ## Agent Skills をインストールする
  51. Claude 及び Claude Desktop では「カスタマイズ」より「スキル」を開き、最新の `freee-api-skill.zip` をダウンロードしてアップロードしてください。
  52. - [最新版をダウンロード (freee-api-skill.zip)](https://github.com/freee/freee-mcp/releases/latest/download/freee-api-skill.zip)
  53. - バージョン履歴から選ぶ: [Releases ページ](https://github.com/freee/freee-mcp/releases)
  54. <img src="docs/images/claude-desktop-skill-upload.png" width="600" alt="Claude Desktop でスキルをアップロード">
  55. Claude Code 等のコーディングエージェント(Cursor, OpenCode など)では、[skills](https://www.npmjs.com/package/skills) でインストールできます。
  56. ```bash
  57. npx skills add freee/freee-mcp
  58. ```
  59. グローバルインストール(`-g`)や特定スキルのみのインストール(`-s`)も可能です。
  60. GitHub CLI(v2.90.0 以降)の [`gh skill`](https://cli.github.com/manual/gh_skill) コマンドからもインストールできます。
  61. ```bash
  62. gh skill install freee/freee-mcp freee-api-skill
  63. ```
  64. `--agent`(例: `claude-code`, `copilot`, `cursor`, `codex`, `gemini-cli`)や `--scope user`/`--scope project` の指定、`--pin` による特定タグ/コミットへの固定にも対応しています。
  65. [Agent Package Manager (APM)](https://github.com/microsoft/apm) を利用している場合は、以下のコマンドでもインストールできます。GitHub Copilot / Claude Code / Cursor / OpenCode / Codex など、プロジェクトに存在する対象ディレクトリに自動でデプロイされます。
  66. ```bash
  67. apm install freee/freee-mcp/skills/freee-api-skill
  68. ```
  69. ## Claude Code Plugin として使う
  70. Claude Code でプラグインとしてインストールすると、Remote MCP サーバー `freee`(`https://mcp.freee.co.jp/mcp`)と Agent Skills(API リファレンス・操作レシピ)がまとめて利用できます。ローカルでのセットアップは不要です。
  71. 以下の2つのコマンドを順に実行してください:
  72. ```bash
  73. claude plugin marketplace add freee/freee-mcp
  74. claude plugin install freee-mcp@freee-mcp-marketplace
  75. ```
  76. Claude Code のプロンプト内からも実行できます:
  77. ```
  78. /plugin marketplace add freee/freee-mcp
  79. /plugin install freee-mcp@freee-mcp-marketplace
  80. ```
  81. インストール後、`/mcp` で `freee` サーバーを選び、ブラウザで freee にログインして認証してください。
  82. プラグインにはローカルの MCP サーバー(`freee-mcp`、`freee-sign-mcp`)は含まれません。freee サイン(電子契約)を使う場合や、自分で登録した freee アプリケーションで接続する場合は「[ローカル MCP を使う場合](#ローカル-mcp-を使う場合)」をご覧ください。
  83. ## Codex Plugin として使う
  84. OpenAI Codex のプラグインマーケットプレース([公式ドキュメント](https://developers.openai.com/codex/plugins))にも対応しており、MCP サーバーと Agent Skills(API リファレンス・操作レシピ)をまとめて利用できます。
  85. Codex CLI からマーケットプレースを追加します:
  86. ```bash
  87. codex plugin marketplace add freee/freee-mcp
  88. ```
  89. その後 Codex を起動し、`/plugins` スラッシュコマンドでプラグイン一覧を開き、`freee-mcp` を選択して `Install plugin` を実行してください。
  90. プラグイン定義は `.codex-plugin/plugin.json`、マーケットプレースカタログは `.agents/plugins/marketplace.json` にあります。
  91. ## Agent Skills の内容
  92. <!-- SKILL-FILE-COUNTS-START -->
  93. | API | 内容 | ファイル数 |
  94. | ------------ | -------------------------------------------------------- | ---------- |
  95. | 会計 | 取引、勘定科目、取引先、請求書、経費申請など | 20 |
  96. | 人事労務 | 従業員、勤怠、給与明細、年末調整など | 11 |
  97. | 請求書 | 請求書、見積書、納品書、領収書、発注書、支払通知書 | 6 |
  98. | 工数管理 | プロジェクト、チーム、パートナー、工数、ユーザーなど | 2 |
  99. | 販売 | 案件、受注、マスタ | 12 |
  100. | IT管理 | メンバー、SaaSアカウント、アプリ、備品、部署、会社など | 1 |
  101. | 固定資産 | 固定資産の一覧、詳細、登録、更新、削除 | 1 |
  102. | 債権管理 | 債権、入金、消込、利用状況 | 2 |
  103. | 業務委託管理 | 業務委託先の企業ユーザー、部門、取引先 | 3 |
  104. | サーベイ | サーベイ企画、実施回(freee-mcp リモート版限定) | 1 |
  105. | 開業 | 開業申請用データ(freee-mcp リモート版限定) | 1 |
  106. | 人事評価 | 人事評価結果(freee-mcp リモート版限定) | 1 |
  107. | 申告 | 法人税申告データ、帳票(別表・決算書など) | 31 |
  108. | サイン | 文書、フォルダ、テンプレート、マイ印鑑など | 8 |
  109. <!-- SKILL-FILE-COUNTS-END -->
  110. AI Agent との会話中に freee API の操作を依頼すると、これらのリファレンスやレシピを参照して正確に実行します。
  111. ## データ作成のベストプラクティス
  112. 請求書や経費精算など、同じ形式のデータを繰り返し作成する場合は、以前に作成したデータを参照することで効率的に作業できます:
  113. - 請求書作成: 過去の請求書を取得して、取引先・品目・税区分などを参考にする
  114. - 経費精算: 過去の申請を参照して、勘定科目や部門の指定を正確に行う
  115. - 取引登録: 類似の取引を参考にして、入力ミスを防ぐ
  116. ```
  117. 例: 「先月の○○社への請求書を参考に、今月分を作成して」
  118. ```
  119. ## 利用可能なツール
  120. ### 管理ツール
  121. | ツール | 説明 | 備考 |
  122. | -------------------------- | ------------------ | ---------------- |
  123. | `freee_authenticate` | OAuth 認証を実行 | stdio のみ |
  124. | `freee_auth_status` | 認証状態を確認 | |
  125. | `freee_clear_auth` | 認証情報をクリア | |
  126. | `freee_set_current_company`| 事業所を切り替え | |
  127. | `freee_get_current_company`| 現在の事業所を表示 | |
  128. | `freee_list_companies` | 事業所一覧を取得 | |
  129. | `freee_current_user` | 現在のユーザー情報 | |
  130. | `freee_server_info` | サーバー情報取得 | |
  131. | `freee_file_upload` | ファイルアップロード | stdio のみ |
  132. ### API ツール
  133. HTTPメソッドごとのシンプルなツール構成:
  134. | ツール | 説明 | 例 |
  135. | ---------------------- | ------------------ | ---------------------------- |
  136. | `freee_api_get` | データ取得 | `/api/1/deals` |
  137. | `freee_api_post` | 新規作成 | `/api/1/deals` |
  138. | `freee_api_put` | 更新 | `/api/1/deals/123` |
  139. | `freee_api_delete` | 削除 | `/api/1/deals/123` |
  140. | `freee_api_patch` | 部分更新 | `/api/1/deals/123` |
  141. | `freee_api_bulk_get` | GET の一括実行 | `/api/1/deals/123` を複数 |
  142. | `freee_api_bulk_write` | 書き込みの一括実行 | POST/PUT/PATCH/DELETE を複数 |
  143. | `freee_api_list_paths` | エンドポイント一覧 | - |
  144. パスは OpenAPI スキーマに対して自動検証されます。
  145. ## freee サイン(電子契約)
  146. freee サインの API は専用コマンド `freee-sign-mcp` で利用できます。
  147. > Remote MCP での提供は現在準備中です。ローカルでの MCP サーバー起動のみサポートしています。
  148. セットアップと MCP 設定は「[freee サイン(freee-sign-mcp)](#freee-サインfreee-sign-mcp)」をご覧ください。
  149. ### サイン用ツール
  150. | ツール | 説明 |
  151. | --- | --- |
  152. | `sign_authenticate` | OAuth 認証を実行 |
  153. | `sign_auth_status` | 認証状態を確認 |
  154. | `sign_clear_auth` | 認証情報をクリア |
  155. | `sign_api_get` | データ取得 |
  156. | `sign_api_post` | 新規作成 |
  157. | `sign_api_put` | 更新 |
  158. | `sign_api_patch` | 部分更新 |
  159. | `sign_api_delete` | 削除 |
  160. ### company_id の取り扱い
  161. リクエスト(パラメータまたはボディ)に `company_id` を含める場合、現在の事業所と一致している必要があります。不一致の場合はエラーになります。
  162. - 事業所の確認: `freee_get_current_company`
  163. - 事業所の切り替え: `freee_set_current_company`
  164. - company_id を含まない API(例: `/api/1/companies`)はそのまま実行可能
  165. ## ローカル MCP を使う場合
  166. 自分で登録した freee アプリケーションの認証情報を使い、MCP サーバーを手元で起動する方法です(stdio)。freee サイン(電子契約)は Remote MCP で提供していないため、サインを使う場合もこちらの手順で `freee-sign-mcp` を設定します。
  167. ローカルモードでは、一部のエンドポイント(freee-mcp リモート版限定)は利用できません。
  168. ### freee-mcp
  169. #### 1. freee アプリケーションの登録
  170. [freee アプリストア](https://app.secure.freee.co.jp/developers) で新しいアプリを作成:
  171. - コールバックURL: `http://127.0.0.1:54321/callback`
  172. - Client ID と Client Secret を取得
  173. - 必要な権限にチェック
  174. #### 2. セットアップ
  175. ```bash
  176. npx freee-mcp configure
  177. ```
  178. 対話式ウィザードが認証情報の設定、OAuth認証、事業所選択を行います。
  179. #### 3. Claude Desktop に追加
  180. `configure` が出力する設定を Claude Desktop の設定ファイルに追加:
  181. ```json
  182. {
  183. "mcpServers": {
  184. "freee": {
  185. "command": "npx",
  186. "args": ["freee-mcp"]
  187. }
  188. }
  189. }
  190. ```
  191. Windows Store (Microsoft Store) 版の Claude Desktop をご利用の場合、設定ファイルのパスが異なります。`freee-mcp configure` は自動的に適切なパスを検出します。
  192. その他の MCP クライアントでは、同じ `command` と `args` をそれぞれの MCP 設定に追加してください。
  193. ### freee サイン(freee-sign-mcp)
  194. #### セットアップ
  195. ```bash
  196. npx --package=freee-mcp -- freee-sign-mcp configure
  197. ```
  198. 対話式ウィザードが認証情報の設定と OAuth 認証を行います。
  199. #### MCP 設定
  200. ```json
  201. {
  202. "mcpServers": {
  203. "freee-sign-mcp": {
  204. "command": "npx",
  205. "args": ["--package=freee-mcp", "--", "freee-sign-mcp"]
  206. }
  207. }
  208. }
  209. ```
  210. ## コントリビューション
  211. 詳しくは [CONTRIBUTING.md](./CONTRIBUTING.md) をご覧ください。
  212. ### Contributors
  213. <!-- CONTRIBUTORS-START -->
  214. <a href="https://github.com/him0"><img src="https://github.com/him0.png" width="40" height="40" alt="@him0"></a>
  215. <a href="https://github.com/dais0n"><img src="https://github.com/dais0n.png" width="40" height="40" alt="@dais0n"></a>
  216. <a href="https://github.com/HikaruEgashira"><img src="https://github.com/HikaruEgashira.png" width="40" height="40" alt="@HikaruEgashira"></a>
  217. <a href="https://github.com/nakanoasaservice"><img src="https://github.com/nakanoasaservice.png" width="40" height="40" alt="@nakanoasaservice"></a>
  218. <a href="https://github.com/tackeyy"><img src="https://github.com/tackeyy.png" width="40" height="40" alt="@tackeyy"></a>
  219. <a href="https://github.com/worldscandy"><img src="https://github.com/worldscandy.png" width="40" height="40" alt="@worldscandy"></a>
  220. <a href="https://github.com/akhr77"><img src="https://github.com/akhr77.png" width="40" height="40" alt="@akhr77"></a>
  221. <a href="https://github.com/trpfrog"><img src="https://github.com/trpfrog.png" width="40" height="40" alt="@trpfrog"></a>
  222. <a href="https://github.com/hoshinotsuyoshi"><img src="https://github.com/hoshinotsuyoshi.png" width="40" height="40" alt="@hoshinotsuyoshi"></a>
  223. <a href="https://github.com/JeongJaeSoon"><img src="https://github.com/JeongJaeSoon.png" width="40" height="40" alt="@JeongJaeSoon"></a>
  224. <a href="https://github.com/norimura114"><img src="https://github.com/norimura114.png" width="40" height="40" alt="@norimura114"></a>
  225. <a href="https://github.com/akiras-ssrd"><img src="https://github.com/akiras-ssrd.png" width="40" height="40" alt="@akiras-ssrd"></a>
  226. <a href="https://github.com/inoue2002"><img src="https://github.com/inoue2002.png" width="40" height="40" alt="@inoue2002"></a>
  227. <a href="https://github.com/jacknocode"><img src="https://github.com/jacknocode.png" width="40" height="40" alt="@jacknocode"></a>
  228. <a href="https://github.com/tnj"><img src="https://github.com/tnj.png" width="40" height="40" alt="@tnj"></a>
  229. <a href="https://github.com/jaxx2104"><img src="https://github.com/jaxx2104.png" width="40" height="40" alt="@jaxx2104"></a>
  230. <a href="https://github.com/kbyk004"><img src="https://github.com/kbyk004.png" width="40" height="40" alt="@kbyk004"></a>
  231. <a href="https://github.com/k4200"><img src="https://github.com/k4200.png" width="40" height="40" alt="@k4200"></a>
  232. <a href="https://github.com/fukumayuta"><img src="https://github.com/fukumayuta.png" width="40" height="40" alt="@fukumayuta"></a>
  233. <a href="https://github.com/kenchan"><img src="https://github.com/kenchan.png" width="40" height="40" alt="@kenchan"></a>
  234. <a href="https://github.com/EijiSugiura"><img src="https://github.com/EijiSugiura.png" width="40" height="40" alt="@EijiSugiura"></a>
  235. <a href="https://github.com/ryuuuuma"><img src="https://github.com/ryuuuuma.png" width="40" height="40" alt="@ryuuuuma"></a>
  236. <a href="https://github.com/toyamagu-2021"><img src="https://github.com/toyamagu-2021.png" width="40" height="40" alt="@toyamagu-2021"></a>
  237. <a href="https://github.com/YasuakiOmokawa"><img src="https://github.com/YasuakiOmokawa.png" width="40" height="40" alt="@YasuakiOmokawa"></a>
  238. <a href="https://github.com/Ryosuke-Watanabe9"><img src="https://github.com/Ryosuke-Watanabe9.png" width="40" height="40" alt="@Ryosuke-Watanabe9"></a>
  239. <a href="https://github.com/Kitamura777"><img src="https://github.com/Kitamura777.png" width="40" height="40" alt="@Kitamura777"></a>
  240. <a href="https://github.com/yuyohi"><img src="https://github.com/yuyohi.png" width="40" height="40" alt="@yuyohi"></a>
  241. <a href="https://github.com/sakura20260508"><img src="https://github.com/sakura20260508.png" width="40" height="40" alt="@sakura20260508"></a>
  242. <a href="https://github.com/bxg06523-cell"><img src="https://github.com/bxg06523-cell.png" width="40" height="40" alt="@bxg06523-cell"></a>
  243. <a href="https://github.com/ryoya1122"><img src="https://github.com/ryoya1122.png" width="40" height="40" alt="@ryoya1122"></a>
  244. <a href="https://github.com/Kanahiro"><img src="https://github.com/Kanahiro.png" width="40" height="40" alt="@Kanahiro"></a>
  245. <a href="https://github.com/kagemeka"><img src="https://github.com/kagemeka.png" width="40" height="40" alt="@kagemeka"></a>
  246. <a href="https://github.com/carrotRakko"><img src="https://github.com/carrotRakko.png" width="40" height="40" alt="@carrotRakko"></a>
  247. <a href="https://github.com/kouiso"><img src="https://github.com/kouiso.png" width="40" height="40" alt="@kouiso"></a>
  248. <a href="https://github.com/jimokada"><img src="https://github.com/jimokada.png" width="40" height="40" alt="@jimokada"></a>
  249. <a href="https://github.com/yuta-takase-ui"><img src="https://github.com/yuta-takase-ui.png" width="40" height="40" alt="@yuta-takase-ui"></a>
  250. <a href="https://github.com/at-k"><img src="https://github.com/at-k.png" width="40" height="40" alt="@at-k"></a>
  251. <a href="https://github.com/paveg"><img src="https://github.com/paveg.png" width="40" height="40" alt="@paveg"></a>
  252. <a href="https://github.com/yoneda1013"><img src="https://github.com/yoneda1013.png" width="40" height="40" alt="@yoneda1013"></a>
  253. <a href="https://github.com/kojamam"><img src="https://github.com/kojamam.png" width="40" height="40" alt="@kojamam"></a>
  254. <a href="https://github.com/nabechindesu"><img src="https://github.com/nabechindesu.png" width="40" height="40" alt="@nabechindesu"></a>
  255. <a href="https://github.com/Hamada-Hiroshi"><img src="https://github.com/Hamada-Hiroshi.png" width="40" height="40" alt="@Hamada-Hiroshi"></a>
  256. <a href="https://github.com/kitasan04"><img src="https://github.com/kitasan04.png" width="40" height="40" alt="@kitasan04"></a>
  257. <a href="https://github.com/Junpei-Nakasone"><img src="https://github.com/Junpei-Nakasone.png" width="40" height="40" alt="@Junpei-Nakasone"></a>
  258. <a href="https://github.com/sakakibara-setu"><img src="https://github.com/sakakibara-setu.png" width="40" height="40" alt="@sakakibara-setu"></a>
  259. <a href="https://github.com/takutin-f"><img src="https://github.com/takutin-f.png" width="40" height="40" alt="@takutin-f"></a>
  260. <a href="https://github.com/byplayer"><img src="https://github.com/byplayer.png" width="40" height="40" alt="@byplayer"></a>
  261. <a href="https://github.com/inomata137"><img src="https://github.com/inomata137.png" width="40" height="40" alt="@inomata137"></a>
  262. <a href="https://github.com/10965401"><img src="https://github.com/10965401.png" width="40" height="40" alt="@10965401"></a>
  263. <a href="https://github.com/nfphys"><img src="https://github.com/nfphys.png" width="40" height="40" alt="@nfphys"></a>
  264. <a href="https://github.com/analyn-cajocson"><img src="https://github.com/analyn-cajocson.png" width="40" height="40" alt="@analyn-cajocson"></a>
  265. <a href="https://github.com/RaphaelP07"><img src="https://github.com/RaphaelP07.png" width="40" height="40" alt="@RaphaelP07"></a>
  266. <a href="https://github.com/faizjamal0111-svg"><img src="https://github.com/faizjamal0111-svg.png" width="40" height="40" alt="@faizjamal0111-svg"></a>
  267. <!-- CONTRIBUTORS-END -->
  268. ## 開発者向け
  269. ```bash
  270. git clone https://github.com/freee/freee-mcp.git
  271. cd freee-mcp
  272. bun install
  273. bun run dev # 開発サーバー(ウォッチモード)
  274. bun run build # ビルド
  275. bun run typecheck # 型チェック
  276. bun run lint # リント
  277. bun run test:run # テスト
  278. # API リファレンスの再生成
  279. bun run generate:references
  280. # OpenAPI スキーマの操作数・パス数を集計(プロダクト別の内訳も表示)
  281. bun run count:apis
  282. ```
  283. ### 技術スタック
  284. TypeScript / Model Context Protocol SDK / OAuth 2.0 + PKCE / Zod / Bun
  285. ### アーキテクチャ詳細
  286. プロジェクトのアーキテクチャ、内部構造、開発ガイドラインについては [CLAUDE.md](./CLAUDE.md) を参照してください。
  287. ## License / ライセンス
  288. [Apache-2.0](./LICENSE)
  289. ## コミュニティ
  290. 質問や情報交換は Discord サーバーで行っています。お気軽にご参加ください。
  291. - [Discord サーバー](https://discord.gg/9ddTPGyxPw)
  292. ## 関連リンク
  293. - [紹介記事: Public API を MCP化するとき Agent Skill 併用が良さそう with freee-mcp](https://zenn.dev/him0/articles/766798ca1315e0)
  294. - [freee API ドキュメント](https://developer.freee.co.jp/docs)
  295. - [Model Context Protocol](https://modelcontextprotocol.io)
src/server/cimd-fetcher.test.ts · Bundled script · 204 lines · 3 findings marked
  1. import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
  2. import { HttpCIMDFetcher, isLocalhostUrl } from './cimd-fetcher.js';
  3. describe('isLocalhostUrl', () => {
  4. it('returns true for localhost / 127.0.0.1 / [::1]', () => {
  5. expect(isLocalhostUrl('http://localhost:3000/metadata')).toBe(true);
  6. expect(isLocalhostUrl('https://localhost/metadata')).toBe(true);
  7. expect(isLocalhostUrl('http://127.0.0.1:3000/metadata')).toBe(true);
  8. expect(isLocalhostUrl('http://[::1]:3000/metadata')).toBe(true);
  9. });
  10. it('returns false for non-loopback hosts', () => {
  11. expect(isLocalhostUrl('http://example.com/metadata')).toBe(false);
  12. expect(isLocalhostUrl('http://10.0.0.1/metadata')).toBe(false);
  13. expect(isLocalhostUrl('http://dev.local/metadata')).toBe(false);
  14. expect(isLocalhostUrl('not-a-url')).toBe(false);
  15. });
  16. });
  17. describe('HttpCIMDFetcher safety gate', () => {
  18. const originalFetch = globalThis.fetch;
  19. // The production gate rejects before we hit the network, so we only need to
  20. // stub fetch for the opt-in cases where the URL is accepted.
  21. const stubFetchReturning = (body: unknown) => {
  22. globalThis.fetch = vi.fn(async () => {
  23. return new Response(JSON.stringify(body), {
  24. status: 200,
  25. headers: { 'Content-Type': 'application/json' },
  26. });
  27. }) as unknown as typeof fetch;
  28. };
  29. beforeEach(() => {
  30. globalThis.fetch = vi.fn(async () => {
  31. throw new Error('fetch should not be called when URL is rejected');
  32. }) as unknown as typeof fetch;
  33. });
  34. afterEach(() => {
  35. globalThis.fetch = originalFetch;
  36. });
  37. const validMetadata = {
  38. redirect_uris: ['http://localhost:3000/oauth/callback'],
  39. client_name: 'test',
  40. token_endpoint_auth_method: 'none',
  41. };
  42. describe('default (allowInsecureLocalhost = false)', () => {
  43. it('rejects http:// URLs', async () => {
  44. const fetcher = new HttpCIMDFetcher();
  45. await expect(fetcher.fetch('http://example.com/metadata')).rejects.toThrow('Unsafe CIMD URL');
  46. });
  47. it('rejects https://localhost', async () => {
  48. const fetcher = new HttpCIMDFetcher();
  49. await expect(fetcher.fetch('https://localhost/metadata')).rejects.toThrow('Unsafe CIMD URL');
  50. });
  51. it('rejects http://localhost', async () => {
  52. const fetcher = new HttpCIMDFetcher();
  53. await expect(fetcher.fetch('http://localhost:3000/metadata')).rejects.toThrow(
  54. 'Unsafe CIMD URL',
  55. );
  56. });
  57. });
  58. describe('allowInsecureLocalhost = true', () => {
  59. it('accepts http://localhost', async () => {
  60. stubFetchReturning(validMetadata);
  61. const fetcher = new HttpCIMDFetcher({ allowInsecureLocalhost: true });
  62. const result = await fetcher.fetch('http://localhost:3000/metadata');
  63. expect(result.client_name).toBe('test');
  64. });
  65. it('accepts http://127.0.0.1', async () => {
  66. stubFetchReturning(validMetadata);
  67. const fetcher = new HttpCIMDFetcher({ allowInsecureLocalhost: true });
  68. await fetcher.fetch('http://127.0.0.1:3000/metadata');
  69. expect(globalThis.fetch).toHaveBeenCalled();
  70. });
  71. it('still rejects http:// to non-loopback hosts (e.g. 10.x.x.x)', async () => {
  72. const fetcher = new HttpCIMDFetcher({ allowInsecureLocalhost: true });
  73. await expect(fetcher.fetch('http://10.0.0.1/metadata')).rejects.toThrow('Unsafe CIMD URL');
  74. });
  75. it('still rejects http:// to public hosts', async () => {
  76. const fetcher = new HttpCIMDFetcher({ allowInsecureLocalhost: true });
  77. await expect(fetcher.fetch('http://example.com/metadata')).rejects.toThrow('Unsafe CIMD URL');
  78. });
  79. });
  80. describe('address checks (production)', () => {
  81. const publicLookup = async () => ['93.184.215.14'];
  82. it.each([
  83. 'https://169.254.169.254/latest/meta-data/',
  84. 'https://100.64.0.1/metadata',
  85. 'https://198.18.0.1/metadata',
    • Dismissed after review: Talks to a raw IP address or throwaway host, where malware is often staged
    • Line 103 on GitHub
  86. 'https://224.0.0.1/metadata',
    • Dismissed after review: Talks to a raw IP address or throwaway host, where malware is often staged
    • Line 104 on GitHub
  87. 'https://2130706433/metadata', // 127.0.0.1 in decimal
  88. 'https://0x7f.1/metadata',
  89. 'https://[::ffff:7f00:1]/metadata',
  90. 'https://[::ffff:169.254.169.254]/metadata',
  91. 'https://[fd00:ec2::254]/metadata',
  92. 'https://[fe80::1]/metadata',
  93. 'https://[64:ff9b::a00:1]/metadata',
  94. 'https://metadata.google.internal/computeMetadata/v1/',
  95. 'https://foo.localhost/metadata',
  96. ])('rejects %s', async (url) => {
  97. const fetcher = new HttpCIMDFetcher({ lookup: publicLookup });
  98. await expect(fetcher.fetch(url)).rejects.toThrow('Unsafe CIMD URL');
  99. });
  100. it.each([
  101. ['127.0.0.1'],
  102. ['169.254.169.254'],
  103. ['10.0.0.5'],
  104. ['::1'],
  105. ['fd00:ec2::254'],
  106. ])('rejects a public hostname that resolves to %s', async (address) => {
  107. const fetcher = new HttpCIMDFetcher({ lookup: async () => ['93.184.215.14', address] });
  108. await expect(fetcher.fetch('https://client.example.com/metadata')).rejects.toThrow(
  109. 'resolves to a non-public address',
  110. );
  111. });
  112. it('rejects when DNS resolution fails', async () => {
  113. const fetcher = new HttpCIMDFetcher({
  114. lookup: async () => {
  115. throw new Error('ENOTFOUND');
  116. },
  117. });
  118. await expect(fetcher.fetch('https://client.example.com/metadata')).rejects.toThrow(
  119. 'DNS resolution failed',
  120. );
  121. });
  122. // Stands in for the pinned HTTPS GET and records where it was told to connect
  123. const requestReturning = (status: number, body: string) =>
  124. vi.fn(async (_url: URL, _address: string) => ({
  125. status,
  126. statusText: '',
  127. body: (async function* () {
  128. yield new TextEncoder().encode(body);
  129. })(),
  130. }));
  131. it('accepts a hostname that resolves only to public addresses', async () => {
  132. const request = requestReturning(200, JSON.stringify(validMetadata));
  133. const fetcher = new HttpCIMDFetcher({ lookup: publicLookup, request });
  134. const result = await fetcher.fetch('https://client.example.com/metadata');
  135. expect(result.client_name).toBe('test');
  136. expect(globalThis.fetch).not.toHaveBeenCalled();
  137. });
  138. it('connects to the validated address and does not resolve the hostname again', async () => {
  139. // A rebinding resolver: public on the first answer, metadata on the next
  140. const answers = [['93.184.215.14'], ['169.254.169.254']];
  141. const lookup = vi.fn(async () => answers.shift() ?? []);
  142. const request = requestReturning(200, JSON.stringify(validMetadata));
  143. const fetcher = new HttpCIMDFetcher({ lookup, request });
  144. await fetcher.fetch('https://client.example.com/metadata');
  145. expect(lookup).toHaveBeenCalledTimes(1);
  146. expect(request).toHaveBeenCalledTimes(1);
  147. const [url, address] = request.mock.calls[0];
  148. expect(url.hostname).toBe('client.example.com');
  149. expect(address).toBe('93.184.215.14');
  150. });
  151. it('connects to an IP literal without a DNS lookup', async () => {
  152. const lookup = vi.fn(publicLookup);
  153. const request = requestReturning(200, JSON.stringify(validMetadata));
  154. const fetcher = new HttpCIMDFetcher({ lookup, request });
  155. await fetcher.fetch('https://93.184.215.14/metadata');
    • Dismissed after review: Talks to a raw IP address or throwaway host, where malware is often staged
    • Line 182 on GitHub
  156. expect(lookup).not.toHaveBeenCalled();
  157. expect(request.mock.calls[0][1]).toBe('93.184.215.14');
  158. });
  159. it('rejects a redirect instead of following it', async () => {
  160. const request = requestReturning(302, '');
  161. const fetcher = new HttpCIMDFetcher({ lookup: publicLookup, request });
  162. await expect(fetcher.fetch('https://client.example.com/metadata')).rejects.toThrow(
  163. 'CIMD fetch failed: 302',
  164. );
  165. });
  166. it('rejects a response larger than 1MB', async () => {
  167. const request = requestReturning(200, 'x'.repeat(1_048_577));
  168. const fetcher = new HttpCIMDFetcher({ lookup: publicLookup, request });
  169. await expect(fetcher.fetch('https://client.example.com/metadata')).rejects.toThrow(
  170. 'too large',
  171. );
  172. });
  173. });
  174. });

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.