YAPI MCP Server

YAPI MCP サーバー

YAPI インスタンスと連携するための Model Context Protocol（MCP）サーバーです。このサーバーを使うと、LLM が YAPI プロジェクトから API ドキュメントの詳細を取得できます。

機能

• インターフェース一覧：プロジェクト内のすべてのインターフェースカテゴリと基本情報を取得します
• インターフェース詳細の取得：ID を指定して、特定のインターフェースの詳細情報を取得します
• インターフェースの検索：タイトルまたはパスのキーワードでインターフェースを検索します

ツール

yapi_list_interfaces

特定の YAPI プロジェクトに含まれるすべてのインターフェースカテゴリと、その中のインターフェースを一覧表示します。

入力：

• project_token（任意）：YAPI プロジェクトのトークンです。YAPI_PROJECT_TOKEN env が設定されている場合は不要です。

戻り値：簡略化されたインターフェースオブジェクト（id、title、path、method、status）を含むカテゴリの JSON 配列です。

yapi_get_interface_details

ID を指定して、特定の YAPI インターフェースの詳細情報を取得します。

入力：

• project_token（任意）：YAPI プロジェクトのトークンです。YAPI_PROJECT_TOKEN env が設定されている場合は不要です。
• interface_id（数値、必須）：特定の YAPI インターフェースの ID です。

戻り値：インターフェース仕様全体（リクエスト／レスポンスパラメーター、ヘッダー、ボディスキーマなど）を含む JSON オブジェクトです。

yapi_search_interfaces

タイトルまたはパスに含まれるキーワードでインターフェースを検索します。

入力：

• project_token（任意）：YAPI プロジェクトのトークンです。YAPI_PROJECT_TOKEN env が設定されている場合は不要です。
• keyword（文字列、必須）：検索するキーワードです。

戻り値：一致したインターフェースとカテゴリ情報を含む JSON 配列です。

前提条件

1. 稼働中の YAPI インスタンス
2. 連携する YAPI プロジェクトのプロジェクトトークンへのアクセス権（YAPI プロジェクトの「Settings」→「Tokens」で確認できます）
3. Node.js 18+ がインストールされていること

環境変数

変数	必須	説明
YAPI_URL	はい	YAPI インスタンスのベース URL（例：http://yapi.example.com）
YAPI_PROJECT_TOKEN	いいえ	デフォルトのプロジェクトトークンです。設定すると、ツール呼び出し時の project_token パラメーターが省略可能になります

インストールと設定

ソースからビルド

git clone <this-repo>
cd yapi-mcp-server
npm install
npm run build

ローカル開発（npm link）

ローカル開発では、npm link を使ってグローバルシンボリックリンクを作成します。

cd yapi-mcp-server
npm link

これにより mcp-server-yapi コマンドをグローバルに利用でき、パスのハードコーディングを避けられます。

Claude Desktop

claude_desktop_config.json に追加します。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%AppData%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yapi": {
      "command": "mcp-server-yapi",
      "env": {
        "YAPI_URL": "<your-yapi-url>",
        "YAPI_PROJECT_TOKEN": "<your-project-token>"
      }
    }
  }
}

Claude Code（CLI）

claude mcp コマンドを使ってサーバーを追加します。

# Add to user config (available in all projects)
claude mcp add-json yapi -s user '{
  "type": "stdio",
  "command": "mcp-server-yapi",
  "env": {
    "YAPI_URL": "<your-yapi-url>",
    "YAPI_PROJECT_TOKEN": "<your-project-token>"
  }
}'

# Or add to project config (only for current project)
claude mcp add-json yapi -s project '{
  "type": "stdio",
  "command": "mcp-server-yapi",
  "env": {
    "YAPI_URL": "<your-yapi-url>",
    "YAPI_PROJECT_TOKEN": "<your-project-token>"
  }
}'

# Verify the configuration
claude mcp list
claude mcp get yapi

Cursor IDE

Cursor の MCP 設定に追加します。

macOS：~/.cursor/mcp.json Windows：%USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "yapi": {
      "command": "mcp-server-yapi",
      "env": {
        "YAPI_URL": "<your-yapi-url>",
        "YAPI_PROJECT_TOKEN": "<your-project-token>"
      }
    }
  }
}

npx の使用（配布におすすめ）

npm に公開されている場合は、バージョン管理を自動化するために npx を使用します。

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-yapi"],
      "env": {
        "YAPI_URL": "<your-yapi-url>",
        "YAPI_PROJECT_TOKEN": "<your-project-token>"
      }
    }
  }
}

使用例

設定が完了したら、Claude に次のように依頼できます。

• 「YAPI プロジェクト内のすべての API を一覧表示して」
• 「インターフェース ID 12345 の詳細を取得して」
• 「プロジェクト内で『user』に関連する API を検索して」
• 「すべての POST エンドポイントを表示して」

トラブルシューティング

サーバーが起動しない

• Node.js 18+ がインストールされていることを確認してください
• dist/index.js へのパスが正しいことを確認してください
• YAPI_URL が設定され、アクセス可能であることを確認してください

認証エラー

• YAPI_PROJECT_TOKEN が正しいことを確認してください
• YAPI プロジェクトの設定でトークンの権限を確認してください

ネットワークエラー

• お使いのマシンから YAPI インスタンスにアクセスできることを確認してください
• 内部ネットワークを使用している場合は、ファイアウォールの設定を確認してください

開発

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Run directly (requires env vars)
YAPI_URL=http://yapi.example.com npm start

ライセンス

MIT