freee-mcp-marketplace
freee 公式の Claude Code プラグインのマーケットプレイス
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
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
Markdown
[](/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
- {
- "name": "freee-mcp-marketplace",
- "owner": {
- "name": "freee"
- },
- "description": "freee 公式の Claude Code プラグインのマーケットプレイス",
- "plugins": [
- {
- "name": "freee-mcp",
- "source": {
- "source": "github",
- "repo": "freee/freee-mcp",
- "ref": "claude-plugin"
- },
- "version": "0.38.2",
- "description": "freee API を MCP 経由で操作するためのスキル。詳細なAPIリファレンス(パラメータ、リクエストボディ、レスポンス情報含む)と、freee-mcp を使用した API 呼び出しガイドを提供。OAuth 認証とトークン管理を自動化し、経費申請、会計データ取得、人事情報管理など、freee の様々な機能を利用可能。"
- }
- ]
- }
README.md · README · 411 lines
- # freee-mcp
- freee会計、人事労務、請求書、工数管理、販売、IT管理、固定資産、債権管理、業務委託管理、サーベイ、開業、人事評価、申告、サイン(電子契約)を AI Agent から操作できるようにする freee 公式の MCP サーバーと Agent Skills です。
- - MCP サーバー: freee API の呼び出し・認証・リクエスト検証を担当
- - Agent Skills: API リファレンスと操作レシピを AI Agent のコンテキストに注入し、正確な API 利用をガイド
- [](https://www.npmjs.com/package/freee-mcp)
- ## 特徴
- - 複数 API 対応: 会計・人事労務・請求書・工数管理・販売・IT管理・固定資産・債権管理・業務委託管理・サーベイ・開業・人事評価・申告の13個の freee API をサポート
- - 対応操作数: <!-- API-STATS-TOTAL-START -->608<!-- API-STATS-TOTAL-END --> 操作(サイン(電子契約)含む、`scripts/generate-references.ts` が自動更新)
- - 利用条件: サーベイ・開業・人事評価・申告は、対応する接続環境、OAuth クライアント、契約プラン、利用者権限が必要
- - サイン(電子契約)対応: freee サインの文書管理 API を専用コマンド(`freee-sign-mcp`)でサポート
- - OAuth 2.0 + PKCE: セキュアな認証フロー、トークン自動更新
- - 複数事業所対応: 事業所の動的切り替えが可能
- ## Agent Skills と MCP の通信の流れ
- Agent Skills(API リファレンス・操作レシピ)と MCP サーバー(API 呼び出し)を組み合わせて利用します。
- ```mermaid
- sequenceDiagram
- participant User as ユーザー
- participant Agent as AI Agent
- participant Skill as Agent Skills<br/>(API リファレンス・操作レシピ)
- participant MCP as MCP サーバー
- participant API as freee API
- User->>Agent: リクエスト<br/>「取引一覧を取得して」
- Note over Agent,Skill: 1. Agent Skills からリファレンスを取得
- Agent->>Skill: freee-api-skill 呼び出し
- Skill-->>Agent: API リファレンス注入<br/>(エンドポイント、パラメータ仕様)
- Note over Agent,MCP: 2. MCP Tool で API を実行
- Agent->>MCP: freee_api_get 呼び出し<br/>path: /api/1/deals
- MCP->>MCP: OpenAPI スキーマで検証
- MCP->>MCP: 認証トークン付与
- Note over MCP,API: 3. freee API への通信
- MCP->>API: GET /api/1/deals<br/>Authorization: Bearer xxx
- API-->>MCP: JSON レスポンス
- MCP-->>Agent: 取引データ
- Agent-->>User: 結果を整形して表示
- ```
- この仕組みにより:
- - Agent Skills: 必要な API リファレンスや操作レシピを段階的にコンテキストに注入(コンテキスト効率化)
- - MCP: 認証・リクエスト検証・API 呼び出しを担当
- ## クイックスタート
- ### 方法 1: Remote MCP で接続する(推奨)
- freee が提供する Remote MCP サーバーに接続する方法です。ローカルでのセットアップが不要で、すぐに利用を開始できます。
- Claude 及び Claude Desktop では「カスタマイズ」より「カスタムコネクタを追加」を開き、以下を設定してください。
- - 名前: `freee`
- - URL: `https://mcp.freee.co.jp/mcp`
- > ⚠️ freee 公式以外の URL を入力しないようにご注意ください。
- <img src="docs/images/claude-desktop-custom-connector.png" width="600" alt="Claude Desktop でカスタムコネクタを追加">
- その他の AI ツールでは、それぞれの案内に従って Remote MCP サーバーを追加してください。
- ### 方法 2: ローカルで MCP サーバーを起動する
- freee アプリケーションを自分で登録し、ローカルで MCP サーバーを起動する方法です。手順は「[ローカル MCP を使う場合](#ローカル-mcp-を使う場合)」をご覧ください。
- ## Agent Skills をインストールする
- Claude 及び Claude Desktop では「カスタマイズ」より「スキル」を開き、最新の `freee-api-skill.zip` をダウンロードしてアップロードしてください。
- - [最新版をダウンロード (freee-api-skill.zip)](https://github.com/freee/freee-mcp/releases/latest/download/freee-api-skill.zip)
- - バージョン履歴から選ぶ: [Releases ページ](https://github.com/freee/freee-mcp/releases)
- <img src="docs/images/claude-desktop-skill-upload.png" width="600" alt="Claude Desktop でスキルをアップロード">
- Claude Code 等のコーディングエージェント(Cursor, OpenCode など)では、[skills](https://www.npmjs.com/package/skills) でインストールできます。
- ```bash
- npx skills add freee/freee-mcp
- ```
- グローバルインストール(`-g`)や特定スキルのみのインストール(`-s`)も可能です。
- GitHub CLI(v2.90.0 以降)の [`gh skill`](https://cli.github.com/manual/gh_skill) コマンドからもインストールできます。
- ```bash
- gh skill install freee/freee-mcp freee-api-skill
- ```
- `--agent`(例: `claude-code`, `copilot`, `cursor`, `codex`, `gemini-cli`)や `--scope user`/`--scope project` の指定、`--pin` による特定タグ/コミットへの固定にも対応しています。
- [Agent Package Manager (APM)](https://github.com/microsoft/apm) を利用している場合は、以下のコマンドでもインストールできます。GitHub Copilot / Claude Code / Cursor / OpenCode / Codex など、プロジェクトに存在する対象ディレクトリに自動でデプロイされます。
- ```bash
- apm install freee/freee-mcp/skills/freee-api-skill
- ```
- ## Claude Code Plugin として使う
- Claude Code でプラグインとしてインストールすると、Remote MCP サーバー `freee`(`https://mcp.freee.co.jp/mcp`)と Agent Skills(API リファレンス・操作レシピ)がまとめて利用できます。ローカルでのセットアップは不要です。
- 以下の2つのコマンドを順に実行してください:
- ```bash
- claude plugin marketplace add freee/freee-mcp
- claude plugin install freee-mcp@freee-mcp-marketplace
- ```
- Claude Code のプロンプト内からも実行できます:
- ```
- /plugin marketplace add freee/freee-mcp
- /plugin install freee-mcp@freee-mcp-marketplace
- ```
- インストール後、`/mcp` で `freee` サーバーを選び、ブラウザで freee にログインして認証してください。
- プラグインにはローカルの MCP サーバー(`freee-mcp`、`freee-sign-mcp`)は含まれません。freee サイン(電子契約)を使う場合や、自分で登録した freee アプリケーションで接続する場合は「[ローカル MCP を使う場合](#ローカル-mcp-を使う場合)」をご覧ください。
- ## Codex Plugin として使う
- OpenAI Codex のプラグインマーケットプレース([公式ドキュメント](https://developers.openai.com/codex/plugins))にも対応しており、MCP サーバーと Agent Skills(API リファレンス・操作レシピ)をまとめて利用できます。
- Codex CLI からマーケットプレースを追加します:
- ```bash
- codex plugin marketplace add freee/freee-mcp
- ```
- その後 Codex を起動し、`/plugins` スラッシュコマンドでプラグイン一覧を開き、`freee-mcp` を選択して `Install plugin` を実行してください。
- プラグイン定義は `.codex-plugin/plugin.json`、マーケットプレースカタログは `.agents/plugins/marketplace.json` にあります。
- ## Agent Skills の内容
- <!-- SKILL-FILE-COUNTS-START -->
- | API | 内容 | ファイル数 |
- | ------------ | -------------------------------------------------------- | ---------- |
- | 会計 | 取引、勘定科目、取引先、請求書、経費申請など | 20 |
- | 人事労務 | 従業員、勤怠、給与明細、年末調整など | 11 |
- | 請求書 | 請求書、見積書、納品書、領収書、発注書、支払通知書 | 6 |
- | 工数管理 | プロジェクト、チーム、パートナー、工数、ユーザーなど | 2 |
- | 販売 | 案件、受注、マスタ | 12 |
- | IT管理 | メンバー、SaaSアカウント、アプリ、備品、部署、会社など | 1 |
- | 固定資産 | 固定資産の一覧、詳細、登録、更新、削除 | 1 |
- | 債権管理 | 債権、入金、消込、利用状況 | 2 |
- | 業務委託管理 | 業務委託先の企業ユーザー、部門、取引先 | 3 |
- | サーベイ | サーベイ企画、実施回(freee-mcp リモート版限定) | 1 |
- | 開業 | 開業申請用データ(freee-mcp リモート版限定) | 1 |
- | 人事評価 | 人事評価結果(freee-mcp リモート版限定) | 1 |
- | 申告 | 法人税申告データ、帳票(別表・決算書など) | 31 |
- | サイン | 文書、フォルダ、テンプレート、マイ印鑑など | 8 |
- <!-- SKILL-FILE-COUNTS-END -->
- AI Agent との会話中に freee API の操作を依頼すると、これらのリファレンスやレシピを参照して正確に実行します。
- ## データ作成のベストプラクティス
- 請求書や経費精算など、同じ形式のデータを繰り返し作成する場合は、以前に作成したデータを参照することで効率的に作業できます:
- - 請求書作成: 過去の請求書を取得して、取引先・品目・税区分などを参考にする
- - 経費精算: 過去の申請を参照して、勘定科目や部門の指定を正確に行う
- - 取引登録: 類似の取引を参考にして、入力ミスを防ぐ
- ```
- 例: 「先月の○○社への請求書を参考に、今月分を作成して」
- ```
- ## 利用可能なツール
- ### 管理ツール
- | ツール | 説明 | 備考 |
- | -------------------------- | ------------------ | ---------------- |
- | `freee_authenticate` | OAuth 認証を実行 | stdio のみ |
- | `freee_auth_status` | 認証状態を確認 | |
- | `freee_clear_auth` | 認証情報をクリア | |
- | `freee_set_current_company`| 事業所を切り替え | |
- | `freee_get_current_company`| 現在の事業所を表示 | |
- | `freee_list_companies` | 事業所一覧を取得 | |
- | `freee_current_user` | 現在のユーザー情報 | |
- | `freee_server_info` | サーバー情報取得 | |
- | `freee_file_upload` | ファイルアップロード | stdio のみ |
- ### API ツール
- HTTPメソッドごとのシンプルなツール構成:
- | ツール | 説明 | 例 |
- | ---------------------- | ------------------ | ---------------------------- |
- | `freee_api_get` | データ取得 | `/api/1/deals` |
- | `freee_api_post` | 新規作成 | `/api/1/deals` |
- | `freee_api_put` | 更新 | `/api/1/deals/123` |
- | `freee_api_delete` | 削除 | `/api/1/deals/123` |
- | `freee_api_patch` | 部分更新 | `/api/1/deals/123` |
- | `freee_api_bulk_get` | GET の一括実行 | `/api/1/deals/123` を複数 |
- | `freee_api_bulk_write` | 書き込みの一括実行 | POST/PUT/PATCH/DELETE を複数 |
- | `freee_api_list_paths` | エンドポイント一覧 | - |
- パスは OpenAPI スキーマに対して自動検証されます。
- ## freee サイン(電子契約)
- freee サインの API は専用コマンド `freee-sign-mcp` で利用できます。
- > Remote MCP での提供は現在準備中です。ローカルでの MCP サーバー起動のみサポートしています。
- セットアップと MCP 設定は「[freee サイン(freee-sign-mcp)](#freee-サインfreee-sign-mcp)」をご覧ください。
- ### サイン用ツール
- | ツール | 説明 |
- | --- | --- |
- | `sign_authenticate` | OAuth 認証を実行 |
- | `sign_auth_status` | 認証状態を確認 |
- | `sign_clear_auth` | 認証情報をクリア |
- | `sign_api_get` | データ取得 |
- | `sign_api_post` | 新規作成 |
- | `sign_api_put` | 更新 |
- | `sign_api_patch` | 部分更新 |
- | `sign_api_delete` | 削除 |
- ### company_id の取り扱い
- リクエスト(パラメータまたはボディ)に `company_id` を含める場合、現在の事業所と一致している必要があります。不一致の場合はエラーになります。
- - 事業所の確認: `freee_get_current_company`
- - 事業所の切り替え: `freee_set_current_company`
- - company_id を含まない API(例: `/api/1/companies`)はそのまま実行可能
- ## ローカル MCP を使う場合
- 自分で登録した freee アプリケーションの認証情報を使い、MCP サーバーを手元で起動する方法です(stdio)。freee サイン(電子契約)は Remote MCP で提供していないため、サインを使う場合もこちらの手順で `freee-sign-mcp` を設定します。
- ローカルモードでは、一部のエンドポイント(freee-mcp リモート版限定)は利用できません。
- ### freee-mcp
- #### 1. freee アプリケーションの登録
- [freee アプリストア](https://app.secure.freee.co.jp/developers) で新しいアプリを作成:
- - コールバックURL: `http://127.0.0.1:54321/callback`
- - Client ID と Client Secret を取得
- - 必要な権限にチェック
- #### 2. セットアップ
- ```bash
- npx freee-mcp configure
- ```
- 対話式ウィザードが認証情報の設定、OAuth認証、事業所選択を行います。
- #### 3. Claude Desktop に追加
- `configure` が出力する設定を Claude Desktop の設定ファイルに追加:
- ```json
- {
- "mcpServers": {
- "freee": {
- "command": "npx",
- "args": ["freee-mcp"]
- }
- }
- }
- ```
- Windows Store (Microsoft Store) 版の Claude Desktop をご利用の場合、設定ファイルのパスが異なります。`freee-mcp configure` は自動的に適切なパスを検出します。
- その他の MCP クライアントでは、同じ `command` と `args` をそれぞれの MCP 設定に追加してください。
- ### freee サイン(freee-sign-mcp)
- #### セットアップ
- ```bash
- npx --package=freee-mcp -- freee-sign-mcp configure
- ```
- 対話式ウィザードが認証情報の設定と OAuth 認証を行います。
- #### MCP 設定
- ```json
- {
- "mcpServers": {
- "freee-sign-mcp": {
- "command": "npx",
- "args": ["--package=freee-mcp", "--", "freee-sign-mcp"]
- }
- }
- }
- ```
- ## コントリビューション
- 詳しくは [CONTRIBUTING.md](./CONTRIBUTING.md) をご覧ください。
- ### Contributors
- <!-- CONTRIBUTORS-START -->
- <a href="https://github.com/him0"><img src="https://github.com/him0.png" width="40" height="40" alt="@him0"></a>
- <a href="https://github.com/dais0n"><img src="https://github.com/dais0n.png" width="40" height="40" alt="@dais0n"></a>
- <a href="https://github.com/HikaruEgashira"><img src="https://github.com/HikaruEgashira.png" width="40" height="40" alt="@HikaruEgashira"></a>
- <a href="https://github.com/nakanoasaservice"><img src="https://github.com/nakanoasaservice.png" width="40" height="40" alt="@nakanoasaservice"></a>
- <a href="https://github.com/tackeyy"><img src="https://github.com/tackeyy.png" width="40" height="40" alt="@tackeyy"></a>
- <a href="https://github.com/worldscandy"><img src="https://github.com/worldscandy.png" width="40" height="40" alt="@worldscandy"></a>
- <a href="https://github.com/akhr77"><img src="https://github.com/akhr77.png" width="40" height="40" alt="@akhr77"></a>
- <a href="https://github.com/trpfrog"><img src="https://github.com/trpfrog.png" width="40" height="40" alt="@trpfrog"></a>
- <a href="https://github.com/hoshinotsuyoshi"><img src="https://github.com/hoshinotsuyoshi.png" width="40" height="40" alt="@hoshinotsuyoshi"></a>
- <a href="https://github.com/JeongJaeSoon"><img src="https://github.com/JeongJaeSoon.png" width="40" height="40" alt="@JeongJaeSoon"></a>
- <a href="https://github.com/norimura114"><img src="https://github.com/norimura114.png" width="40" height="40" alt="@norimura114"></a>
- <a href="https://github.com/akiras-ssrd"><img src="https://github.com/akiras-ssrd.png" width="40" height="40" alt="@akiras-ssrd"></a>
- <a href="https://github.com/inoue2002"><img src="https://github.com/inoue2002.png" width="40" height="40" alt="@inoue2002"></a>
- <a href="https://github.com/jacknocode"><img src="https://github.com/jacknocode.png" width="40" height="40" alt="@jacknocode"></a>
- <a href="https://github.com/tnj"><img src="https://github.com/tnj.png" width="40" height="40" alt="@tnj"></a>
- <a href="https://github.com/jaxx2104"><img src="https://github.com/jaxx2104.png" width="40" height="40" alt="@jaxx2104"></a>
- <a href="https://github.com/kbyk004"><img src="https://github.com/kbyk004.png" width="40" height="40" alt="@kbyk004"></a>
- <a href="https://github.com/k4200"><img src="https://github.com/k4200.png" width="40" height="40" alt="@k4200"></a>
- <a href="https://github.com/fukumayuta"><img src="https://github.com/fukumayuta.png" width="40" height="40" alt="@fukumayuta"></a>
- <a href="https://github.com/kenchan"><img src="https://github.com/kenchan.png" width="40" height="40" alt="@kenchan"></a>
- <a href="https://github.com/EijiSugiura"><img src="https://github.com/EijiSugiura.png" width="40" height="40" alt="@EijiSugiura"></a>
- <a href="https://github.com/ryuuuuma"><img src="https://github.com/ryuuuuma.png" width="40" height="40" alt="@ryuuuuma"></a>
- <a href="https://github.com/toyamagu-2021"><img src="https://github.com/toyamagu-2021.png" width="40" height="40" alt="@toyamagu-2021"></a>
- <a href="https://github.com/YasuakiOmokawa"><img src="https://github.com/YasuakiOmokawa.png" width="40" height="40" alt="@YasuakiOmokawa"></a>
- <a href="https://github.com/Ryosuke-Watanabe9"><img src="https://github.com/Ryosuke-Watanabe9.png" width="40" height="40" alt="@Ryosuke-Watanabe9"></a>
- <a href="https://github.com/Kitamura777"><img src="https://github.com/Kitamura777.png" width="40" height="40" alt="@Kitamura777"></a>
- <a href="https://github.com/yuyohi"><img src="https://github.com/yuyohi.png" width="40" height="40" alt="@yuyohi"></a>
- <a href="https://github.com/sakura20260508"><img src="https://github.com/sakura20260508.png" width="40" height="40" alt="@sakura20260508"></a>
- <a href="https://github.com/bxg06523-cell"><img src="https://github.com/bxg06523-cell.png" width="40" height="40" alt="@bxg06523-cell"></a>
- <a href="https://github.com/ryoya1122"><img src="https://github.com/ryoya1122.png" width="40" height="40" alt="@ryoya1122"></a>
- <a href="https://github.com/Kanahiro"><img src="https://github.com/Kanahiro.png" width="40" height="40" alt="@Kanahiro"></a>
- <a href="https://github.com/kagemeka"><img src="https://github.com/kagemeka.png" width="40" height="40" alt="@kagemeka"></a>
- <a href="https://github.com/carrotRakko"><img src="https://github.com/carrotRakko.png" width="40" height="40" alt="@carrotRakko"></a>
- <a href="https://github.com/kouiso"><img src="https://github.com/kouiso.png" width="40" height="40" alt="@kouiso"></a>
- <a href="https://github.com/jimokada"><img src="https://github.com/jimokada.png" width="40" height="40" alt="@jimokada"></a>
- <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>
- <a href="https://github.com/at-k"><img src="https://github.com/at-k.png" width="40" height="40" alt="@at-k"></a>
- <a href="https://github.com/paveg"><img src="https://github.com/paveg.png" width="40" height="40" alt="@paveg"></a>
- <a href="https://github.com/yoneda1013"><img src="https://github.com/yoneda1013.png" width="40" height="40" alt="@yoneda1013"></a>
- <a href="https://github.com/kojamam"><img src="https://github.com/kojamam.png" width="40" height="40" alt="@kojamam"></a>
- <a href="https://github.com/nabechindesu"><img src="https://github.com/nabechindesu.png" width="40" height="40" alt="@nabechindesu"></a>
- <a href="https://github.com/Hamada-Hiroshi"><img src="https://github.com/Hamada-Hiroshi.png" width="40" height="40" alt="@Hamada-Hiroshi"></a>
- <a href="https://github.com/kitasan04"><img src="https://github.com/kitasan04.png" width="40" height="40" alt="@kitasan04"></a>
- <a href="https://github.com/Junpei-Nakasone"><img src="https://github.com/Junpei-Nakasone.png" width="40" height="40" alt="@Junpei-Nakasone"></a>
- <a href="https://github.com/sakakibara-setu"><img src="https://github.com/sakakibara-setu.png" width="40" height="40" alt="@sakakibara-setu"></a>
- <a href="https://github.com/takutin-f"><img src="https://github.com/takutin-f.png" width="40" height="40" alt="@takutin-f"></a>
- <a href="https://github.com/byplayer"><img src="https://github.com/byplayer.png" width="40" height="40" alt="@byplayer"></a>
- <a href="https://github.com/inomata137"><img src="https://github.com/inomata137.png" width="40" height="40" alt="@inomata137"></a>
- <a href="https://github.com/10965401"><img src="https://github.com/10965401.png" width="40" height="40" alt="@10965401"></a>
- <a href="https://github.com/nfphys"><img src="https://github.com/nfphys.png" width="40" height="40" alt="@nfphys"></a>
- <a href="https://github.com/analyn-cajocson"><img src="https://github.com/analyn-cajocson.png" width="40" height="40" alt="@analyn-cajocson"></a>
- <a href="https://github.com/RaphaelP07"><img src="https://github.com/RaphaelP07.png" width="40" height="40" alt="@RaphaelP07"></a>
- <a href="https://github.com/faizjamal0111-svg"><img src="https://github.com/faizjamal0111-svg.png" width="40" height="40" alt="@faizjamal0111-svg"></a>
- <!-- CONTRIBUTORS-END -->
- ## 開発者向け
- ```bash
- git clone https://github.com/freee/freee-mcp.git
- cd freee-mcp
- bun install
- bun run dev # 開発サーバー(ウォッチモード)
- bun run build # ビルド
- bun run typecheck # 型チェック
- bun run lint # リント
- bun run test:run # テスト
- # API リファレンスの再生成
- bun run generate:references
- # OpenAPI スキーマの操作数・パス数を集計(プロダクト別の内訳も表示)
- bun run count:apis
- ```
- ### 技術スタック
- TypeScript / Model Context Protocol SDK / OAuth 2.0 + PKCE / Zod / Bun
- ### アーキテクチャ詳細
- プロジェクトのアーキテクチャ、内部構造、開発ガイドラインについては [CLAUDE.md](./CLAUDE.md) を参照してください。
- ## License / ライセンス
- [Apache-2.0](./LICENSE)
- ## コミュニティ
- 質問や情報交換は Discord サーバーで行っています。お気軽にご参加ください。
- - [Discord サーバー](https://discord.gg/9ddTPGyxPw)
- ## 関連リンク
- - [紹介記事: Public API を MCP化するとき Agent Skill 併用が良さそう with freee-mcp](https://zenn.dev/him0/articles/766798ca1315e0)
- - [freee API ドキュメント](https://developer.freee.co.jp/docs)
- - [Model Context Protocol](https://modelcontextprotocol.io)
src/server/cimd-fetcher.test.ts · Bundled script · 204 lines · 3 findings marked
- import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
- import { HttpCIMDFetcher, isLocalhostUrl } from './cimd-fetcher.js';
- describe('isLocalhostUrl', () => {
- it('returns true for localhost / 127.0.0.1 / [::1]', () => {
- expect(isLocalhostUrl('http://localhost:3000/metadata')).toBe(true);
- expect(isLocalhostUrl('https://localhost/metadata')).toBe(true);
- expect(isLocalhostUrl('http://127.0.0.1:3000/metadata')).toBe(true);
- expect(isLocalhostUrl('http://[::1]:3000/metadata')).toBe(true);
- });
- it('returns false for non-loopback hosts', () => {
- expect(isLocalhostUrl('http://example.com/metadata')).toBe(false);
- expect(isLocalhostUrl('http://10.0.0.1/metadata')).toBe(false);
- expect(isLocalhostUrl('http://dev.local/metadata')).toBe(false);
- expect(isLocalhostUrl('not-a-url')).toBe(false);
- });
- });
- describe('HttpCIMDFetcher safety gate', () => {
- const originalFetch = globalThis.fetch;
- // The production gate rejects before we hit the network, so we only need to
- // stub fetch for the opt-in cases where the URL is accepted.
- const stubFetchReturning = (body: unknown) => {
- globalThis.fetch = vi.fn(async () => {
- return new Response(JSON.stringify(body), {
- status: 200,
- headers: { 'Content-Type': 'application/json' },
- });
- }) as unknown as typeof fetch;
- };
- beforeEach(() => {
- globalThis.fetch = vi.fn(async () => {
- throw new Error('fetch should not be called when URL is rejected');
- }) as unknown as typeof fetch;
- });
- afterEach(() => {
- globalThis.fetch = originalFetch;
- });
- const validMetadata = {
- redirect_uris: ['http://localhost:3000/oauth/callback'],
- client_name: 'test',
- token_endpoint_auth_method: 'none',
- };
- describe('default (allowInsecureLocalhost = false)', () => {
- it('rejects http:// URLs', async () => {
- const fetcher = new HttpCIMDFetcher();
- await expect(fetcher.fetch('http://example.com/metadata')).rejects.toThrow('Unsafe CIMD URL');
- });
- it('rejects https://localhost', async () => {
- const fetcher = new HttpCIMDFetcher();
- await expect(fetcher.fetch('https://localhost/metadata')).rejects.toThrow('Unsafe CIMD URL');
- });
- it('rejects http://localhost', async () => {
- const fetcher = new HttpCIMDFetcher();
- await expect(fetcher.fetch('http://localhost:3000/metadata')).rejects.toThrow(
- 'Unsafe CIMD URL',
- );
- });
- });
- describe('allowInsecureLocalhost = true', () => {
- it('accepts http://localhost', async () => {
- stubFetchReturning(validMetadata);
- const fetcher = new HttpCIMDFetcher({ allowInsecureLocalhost: true });
- const result = await fetcher.fetch('http://localhost:3000/metadata');
- expect(result.client_name).toBe('test');
- });
- it('accepts http://127.0.0.1', async () => {
- stubFetchReturning(validMetadata);
- const fetcher = new HttpCIMDFetcher({ allowInsecureLocalhost: true });
- await fetcher.fetch('http://127.0.0.1:3000/metadata');
- expect(globalThis.fetch).toHaveBeenCalled();
- });
- it('still rejects http:// to non-loopback hosts (e.g. 10.x.x.x)', async () => {
- const fetcher = new HttpCIMDFetcher({ allowInsecureLocalhost: true });
- await expect(fetcher.fetch('http://10.0.0.1/metadata')).rejects.toThrow('Unsafe CIMD URL');
- });
- it('still rejects http:// to public hosts', async () => {
- const fetcher = new HttpCIMDFetcher({ allowInsecureLocalhost: true });
- await expect(fetcher.fetch('http://example.com/metadata')).rejects.toThrow('Unsafe CIMD URL');
- });
- });
- describe('address checks (production)', () => {
- const publicLookup = async () => ['93.184.215.14'];
- it.each([
- 'https://169.254.169.254/latest/meta-data/',
- 'https://100.64.0.1/metadata',
- '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
- '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
- 'https://2130706433/metadata', // 127.0.0.1 in decimal
- 'https://0x7f.1/metadata',
- 'https://[::ffff:7f00:1]/metadata',
- 'https://[::ffff:169.254.169.254]/metadata',
- 'https://[fd00:ec2::254]/metadata',
- 'https://[fe80::1]/metadata',
- 'https://[64:ff9b::a00:1]/metadata',
- 'https://metadata.google.internal/computeMetadata/v1/',
- 'https://foo.localhost/metadata',
- ])('rejects %s', async (url) => {
- const fetcher = new HttpCIMDFetcher({ lookup: publicLookup });
- await expect(fetcher.fetch(url)).rejects.toThrow('Unsafe CIMD URL');
- });
- it.each([
- ['127.0.0.1'],
- ['169.254.169.254'],
- ['10.0.0.5'],
- ['::1'],
- ['fd00:ec2::254'],
- ])('rejects a public hostname that resolves to %s', async (address) => {
- const fetcher = new HttpCIMDFetcher({ lookup: async () => ['93.184.215.14', address] });
- await expect(fetcher.fetch('https://client.example.com/metadata')).rejects.toThrow(
- 'resolves to a non-public address',
- );
- });
- it('rejects when DNS resolution fails', async () => {
- const fetcher = new HttpCIMDFetcher({
- lookup: async () => {
- throw new Error('ENOTFOUND');
- },
- });
- await expect(fetcher.fetch('https://client.example.com/metadata')).rejects.toThrow(
- 'DNS resolution failed',
- );
- });
- // Stands in for the pinned HTTPS GET and records where it was told to connect
- const requestReturning = (status: number, body: string) =>
- vi.fn(async (_url: URL, _address: string) => ({
- status,
- statusText: '',
- body: (async function* () {
- yield new TextEncoder().encode(body);
- })(),
- }));
- it('accepts a hostname that resolves only to public addresses', async () => {
- const request = requestReturning(200, JSON.stringify(validMetadata));
- const fetcher = new HttpCIMDFetcher({ lookup: publicLookup, request });
- const result = await fetcher.fetch('https://client.example.com/metadata');
- expect(result.client_name).toBe('test');
- expect(globalThis.fetch).not.toHaveBeenCalled();
- });
- it('connects to the validated address and does not resolve the hostname again', async () => {
- // A rebinding resolver: public on the first answer, metadata on the next
- const answers = [['93.184.215.14'], ['169.254.169.254']];
- const lookup = vi.fn(async () => answers.shift() ?? []);
- const request = requestReturning(200, JSON.stringify(validMetadata));
- const fetcher = new HttpCIMDFetcher({ lookup, request });
- await fetcher.fetch('https://client.example.com/metadata');
- expect(lookup).toHaveBeenCalledTimes(1);
- expect(request).toHaveBeenCalledTimes(1);
- const [url, address] = request.mock.calls[0];
- expect(url.hostname).toBe('client.example.com');
- expect(address).toBe('93.184.215.14');
- });
- it('connects to an IP literal without a DNS lookup', async () => {
- const lookup = vi.fn(publicLookup);
- const request = requestReturning(200, JSON.stringify(validMetadata));
- const fetcher = new HttpCIMDFetcher({ lookup, request });
- 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
- expect(lookup).not.toHaveBeenCalled();
- expect(request.mock.calls[0][1]).toBe('93.184.215.14');
- });
- it('rejects a redirect instead of following it', async () => {
- const request = requestReturning(302, '');
- const fetcher = new HttpCIMDFetcher({ lookup: publicLookup, request });
- await expect(fetcher.fetch('https://client.example.com/metadata')).rejects.toThrow(
- 'CIMD fetch failed: 302',
- );
- });
- it('rejects a response larger than 1MB', async () => {
- const request = requestReturning(200, 'x'.repeat(1_048_577));
- const fetcher = new HttpCIMDFetcher({ lookup: publicLookup, request });
- await expect(fetcher.fetch('https://client.example.com/metadata')).rejects.toThrow(
- 'too large',
- );
- });
- });
- });
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.