YApi MCP Bridge

Model Context Protocol（MCP） に基づく YApi Server で、MCP 対応の AI クライアントが YApi インターフェースを照会・検索・作成・更新できるようにします。

機能

現在、以下のツールを提供しています：

Server は削除ツールを提供しません。AI クライアントが誤って不可逆操作を実行するのを防ぐためです。

Related MCP server: YApi MCP Server

npm でインストール

リポジトリをクローンする必要はなく、直接実行できます：

npx -y yapi-mcp-bridge

グローバルインストールも可能です：

npm install -g yapi-mcp-bridge
yapi-mcp-bridge

グローバルインストール後、以下のコマンドでツール呼び出し統計を確認できます：

yapi-mcp-stats

ソースからインストール

環境要件

• Node.js 18 以上

• 正常にアクセスできる YApi インスタンス

• 対応するプロジェクトへのアクセス権限を持つ YApi Cookie

ソースから実行するには、さらに pnpm 10 以上が必要です。macOS では Homebrew で Node.js と pnpm をインストールできます：

brew install node pnpm

依存関係のインストール

プロジェクトディレクトリに入って実行：

pnpm install

YApi の設定

環境変数のサンプルをコピー：

cp .env.example .env

.env を編集：

YAPI_HOST=https://yapi.example.com
YAPI_COOKIE=_yapi_token=xxx;_yapi_uid=xx;

パラメータの説明：

• YAPI_HOST：YApi サービスのアドレス。プロトコルとドメインのみを記入し、/api を含めないでください。

• YAPI_COOKIE：YApi にアクセスする際に使用する完全な Cookie 文字列。

• YAPI_LOG_FILE：オプションのログファイルパス。デフォルトは ~/.yapi-mcp/logs/yapi-mcp.log。

YApi にログイン後、ブラウザの開発者ツールの Network パネルで任意の YApi リクエストを選択し、Request Headers から Cookie をコピーできます。Cookie はログイン資格情報と同等なので、Git にコミットしたり他人と共有したりしないでください。このプロジェクトはデフォルトで .env を無視します。

Server の起動

プロジェクトのルートディレクトリで実行：

pnpm start

これは stdio MCP Server です。直接起動しても通常の HTTP ページはなく、対話プロンプトも表示されません。MCP クライアントが標準入出力を介して通信するのを待ちます。

起動に成功すると、Server は stderr に類似の情報を出力します。MCP 通信に使用する stdout を汚染しません：

[yapi-mcp] server started (stdio), tools=9, log=~/.yapi-mcp/logs/yapi-mcp.log

テストを実行：

pnpm test

MCP クライアントへの接続

npm パッケージを使用する場合、stdio MCP Server をサポートするクライアントに以下の設定を追加します：

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": [
        "-y",
        "yapi-mcp-bridge"
      ],
      "env": {
        "YAPI_HOST": "https://yapi.example.com",
        "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
      }
    }
  }
}

ソースから起動する場合は、Node.js の絶対パス設定を引き続き使用できます：

{
  "command": "node",
  "args": ["/absolute/path/to/yapi-mcp-server/src/index.js"],
  "env": {
    "YAPI_HOST": "https://yapi.example.com",
    "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
  }
}

設定を変更したら、MCP クライアントを再起動または再読み込みします。クライアントは yapi_ で始まる 9 つのツールを検出できるはずです。

使用

接続後、自然言語で AI クライアントに YApi を操作させることができます。

プロジェクトとインターフェースの照会

获取 YApi 项目 1922 的详情。

列出 YApi 项目 1922 的所有接口分类。

在 YApi 项目 1922 中搜索路径包含 /order 的接口，并获取匹配接口的常用定义。

yapi_get_interface はデフォルトで以下の一般的な情報のみを返します：

• インターフェース ID、タイトル、HTTP メソッド、パス

• インターフェースの説明

• Path、Query、Header、Body の入力パラメータ

• レスポンスタイプとレスポンス内容

YApi のメタデータを調査したり、元のレスポンスを取得する必要がある場合は、明示的に full: true を要求できます：

获取 YApi 接口 5001 的原始全量数据。

インターフェースカテゴリの作成

在 YApi 项目 1922 中创建一个名为“订单管理”的接口分类。

インターフェースの作成

在 YApi 项目 1922、分类 3001 中创建接口：
标题为“创建订单”，方法为 POST，路径为 /orders，
请求体类型为 JSON，请求示例为 {"productId": 1001, "quantity": 2}，
响应示例为 {"id": 9001, "status": "created"}。

インターフェース作成時の必須パラメータ：

requestBody と responseBody は文字列で渡す必要があります。内容が JSON または JSON Schema の場合も、先に文字列にシリアライズする必要があります。

インターフェースの更新

把 YApi 接口 5001 的标题修改为“查询订单详情”，状态修改为 done，并添加 order 标签。

更新にはインターフェース ID と変更するフィールドのみを指定します。指定されていないフィールドは YApi に送信されません。

ログと呼び出し統計

Server はデフォルトでログを次の場所に書き込みます：

~/.yapi-mcp/logs/yapi-mcp.log

ログは JSON Lines 形式で、各行が 1 つのイベントです。例：

{"timestamp":"2026-08-21T08:00:00.000Z","event":"tool_call","tool":"yapi_get_interface","status":"success","durationMs":128}

ツールログにはツール名、呼び出しステータス、所要時間のみが記録され、呼び出しパラメータ、インターフェース内容、Cookie、その他の資格情報は記録されません。

ログが 1000 件を超えると、Server は自動的に最も古い 300 件を削除し、ログファイルが増え続けるのを防ぎます。

ツールの呼び出し頻度、成功数、失敗数、平均所要時間を確認：

# 全局安装
yapi-mcp-stats

# 从源码运行
pnpm stats

YAPI_LOG_FILE でログの場所を変更できます。相対パスを使用する場合、Server の起動ディレクトリを基準に解決されます。MCP クライアントでは絶対パスを設定することをお勧めします。

よくある質問

「ログインしてください」または権限がないと返される

以下を確認してください：

• YAPI_COOKIE が完全で、期限切れでないか。

• 現在の Cookie に対応するユーザーがプロジェクトへのアクセスまたは編集権限を持っているか。

• Cookie を変更した後、MCP Server を再起動したか。

クライアントが Server を見つけられない

• MCP 設定の src/index.js が絶対パスであることを確認。

• command が実行可能な Node.js を指していることを確認。

• プロジェクトディレクトリで pnpm test を実行し、依存関係と実行環境が正常であることを確認。

.env を変更しても反映されない

.env はデフォルトで Server の現在の作業ディレクトリから読み込まれます。ターミナルで起動する場合はプロジェクトのルートディレクトリで pnpm start を実行してください。MCP クライアントで起動する場合は、設定の env で YAPI_HOST と YAPI_COOKIE を明示的に渡すことをお勧めします。

プロジェクト構造

src/
├── handlers/       # MCP 工具 handler 与 YApi 方法映射
├── tools/          # 工具定义、Zod 输入输出 Schema
├── index.js        # stdio Server 入口
├── server.js       # McpServer 注册
└── yapi.js         # YApi HTTP API 封装
test/               # 单元测试与 MCP 注册测试

セキュリティに関する注意

• .env や YApi Cookie をコミットしないでください。

• 書き込みツールは YApi データを実際に変更します。実行前にプロジェクト ID、カテゴリ ID、インターフェース ID を確認してください。

• 権限範囲ができるだけ小さい YApi アカウントを使用することをお勧めします。

• デフォルトのログはユーザーディレクトリの .yapi-mcp/logs/ に保存され、npm インストールディレクトリには書き込まれません。