Microsoft Forms API

msforms-api

フォームの確認、分岐の解決、回答の検証、ファイルのアップロード、回答の送信、回答リンクの保存を行う、AI ネイティブな Microsoft Forms 自動化ツールです。

次の方法で利用できます。

1. MCP サーバー：AI エージェントやエディター向け — ほとんどのユーザーにおすすめです。
2. エージェントスキル：シェルコマンドを実行できるエージェント向けの CLI を利用します。
3. CLI：スクリプトやターミナルでのワークフロー向けです。
4. TypeScript SDK：カスタムアプリケーション向けです。

メモ

このプロジェクトは、Autopilot モードで Extra High の推論設定を使用し、 GPT-5.6 Sol を搭載した GitHub Copilot App によって生成されました。

警告

このプロジェクトは、リバースエンジニアリングされた Microsoft Forms のウェブ API を使用しています。Microsoft はこれらのエンドポイントを 文書化も保証もしていません。予告なく変更される場合があります。 このプロジェクトは Microsoft との提携関係になく、Microsoft の承認も受けていません。

クイックスタート

前提条件

• Node.js 22 以降。
• Google Chrome または Microsoft Edge。どちらも利用できない場合は、Playwright Chromium が自動的にインストールされます。

エージェントスキルとしてインストールする

CLI スキルは、分岐の確認、回答の準備と検証、許可されたファイルのアップロード、送信前に明示的な承認を求める方法をエージェントに教えます。

npx -y skills add Maxim-Mazurok/msforms-api

インストーラーは、Claude Code、Cursor、GitHub Copilot、Codex などのサポート対象エージェントを検出し、スキルのインストール先を尋ねます。プロジェクト間で使用するには、グローバルスコープを選択してください。

このスキルは npx を通じて msforms-api を実行するため、グローバルパッケージのインストールも MCP の設定も必要ありません。MCP サーバーの代替インターフェースであり、どちらも同じ CLI と SDK の動作を使用します。

AI ツールへのインストール

上のインストールバッジをクリックするか、この MCP 設定を使用してください。Cursor の場合は、~/.cursor/mcp.json として保存します。

{
  "mcpServers": {
    "microsoft-forms": {
      "command": "npx",
      "args": ["-y", "-p", "msforms-api@latest", "msforms-api-mcp"]
    }
  }
}

初回使用時に、エージェントに Microsoft Forms の認証を依頼してください。ブラウザーが開いてサインインすると、以降の操作では永続セッションが再利用されます。

次のように試してみてください。

この Microsoft Form を確認し、すべての質問、入力規則、ファイルのアップロードルール、分岐について説明してください：https://forms.cloud.microsoft/...

エージェントは、送信せずに回答を準備して検証できます。送信には別の破壊的な MCP ツールを使用し、明示的な確認が必要です。

code --add-mcp '{"name":"microsoft-forms","command":"npx","args":["-y","-p","msforms-api@latest","msforms-api-mcp"]}'

code --add-mcp '{"name":"microsoft-forms","command":"npx","args":["-y","-p","msforms-api@latest","msforms-api-mcp"]}'

claude mcp add microsoft-forms -- npx -y -p msforms-api@latest msforms-api-mcp

エージェントにできること

• 生の API オブジェクトを含む、フォームの完全なメタデータを読み取ります。
• 質問の種類、選択肢、必須状態、テキストの入力規則を把握します。
• 安定した質問識別子を使用して、選択肢の分岐を解決します。
• マトリックスの行と、それらに共通する選択肢を確認します。
• ファイル数、サイズ、拡張子の制限を確認します。
• 送信せずに回答を検証し、シリアライズします。
• 認証済みの Forms フロントエンドを通じてファイルをアップロードします。
• 明示的な確認を得た後にのみ送信します。
• サインイン済みアカウントに回答リンクを保存し、一覧表示します。

MCP ツール

forms_submit は破壊的かつ非冪等としてマークされています。MCP v2 の複数ラウンドトリップによる確認要求を使用します。確認が拒否された場合、または確認が false の場合、送信コードには到達しません。

ワークフロー全般と安全性に関するガイダンスも、次から利用できます。

npx -y -p msforms-api@latest msforms-api guide

CLI

グローバルにインストールせずに実行します。

# Sign in once
npx -y -p msforms-api@latest msforms-api auth

# Inspect a form
npx -y -p msforms-api@latest msforms-api inspect \
  --form 'https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=...'

# Validate answers without submitting
npx -y -p msforms-api@latest msforms-api validate \
  --form 'https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=...' \
  --answers @answers.json

# Submit only when intended
npx -y -p msforms-api@latest msforms-api submit \
  --form 'https://forms.cloud.microsoft/Pages/ResponsePage.aspx?id=...' \
  --answers @answers.json \
  --save-response \
  --confirm

CLI を頻繁に使う場合は、グローバルにインストールできます。

npm install --global msforms-api
msforms-api auth

すべてのコマンドは JSON を出力します。1 行で出力するには --compact を追加してください。

認証とローカルデータ

認証時には表示されるブラウザーが開き、プロファイルは次の場所に保存されます。

~/.msforms-api/browser-profile

SDK はそのプロファイルを使用して、スコープが制限された Forms の Cookie、偽造防止トークン、セッションメタデータを取得します。これらの認証情報が出力または返されることはありません。通常の読み取りと送信には、Forms への直接 HTTP リクエストを使用します。Forms フロントエンドが SharePoint の認証を管理するため、ファイルのアップロードにはブラウザーを使用します。

プロファイルまたはブラウザーを変更するには、次のようにします。

msforms-api --profile ~/.config/my-forms-profile --browser chrome auth

MCP 環境変数：

ローカルセッションを削除するには、~/.msforms-api/browser-profile を削除してください。

回答形式

回答は、forms_inspect が返す正確な質問 ID に対応付けます。

マトリックスの回答には、マトリックスグループ ID ではなく、各行の質問 ID を使用します。

{
  "text-question-id": "Ada Lovelace",
  "multiple-choice-question-id": ["Desktop", "Laptop"],
  "date-question-id": "2026-08-12",
  "ranking-question-id": ["Branching", "Uploads", "Ratings"],
  "matrix-row-question-id": { "label": "Agree" },
  "file-question-id": [
    {
      "name": "document.pdf",
      "uploadSessionUrl": "https://...",
      "link": "https://...",
      "badgerToken": null,
      "time": 1786492949627,
      "status": 3,
      "id": "sharepoint-item-id"
    }
  ]
}

SDK

npm install msforms-api

import { MicrosoftFormsClient } from "msforms-api";

const client = new MicrosoftFormsClient();
const form = await client.getForm(formUrl);

const answers = {
  [form.questions[0].id]: "Example answer",
};

const validation = await client.validateAnswers(formUrl, answers);
if (!validation.valid) {
  throw new Error(JSON.stringify(validation.issues));
}

const submission = await client.submitResponse(formUrl, answers, {
  saveResponse: true,
});

if (submission.saveResponseStatus === "failed") {
  console.error(submission.saveResponseError);
  await client.saveResponse(
    formUrl,
    submission.responseId,
    submission.submitDate,
  );
}

submitResponse() は SDK レベルで直接呼び出せます。SDK を使用するアプリケーションは、独自のユーザー確認境界を実装する必要があります。CLI では --confirm が必要で、MCP ではエリシテーションが必要です。

submissionStatus: "submitted" または返された responseId は、永続的な回答が存在することを意味します。要求された回答リンクの保存は、独立して失敗する場合があります。その場合、saveResponseStatus は "failed" となり、送信の詳細は結果に残るため、呼び出し元は再送信してはいけません。冪等な saveResponse() 操作のみを再試行してください。

フォームの構造

正規化されたフォームモデルには、次の情報が含まれます。

• ID、タイトル、サブタイトル、順序、種類、必須状態。
• 選択肢のラベルと branchTargetId の値。
• 継承された選択肢を含むマトリックスの行。
• テキストの検証境界とルール。
• ファイルのアップロード制限。
• 解析済みのフォーム設定。
• 前方互換性のための、フォームと質問の完全な生オブジェクト。

分岐の例：

{
  "id": "source-question-id",
  "type": "Question.Choice",
  "options": [
    {
      "label": "Yes",
      "branchTargetId": "target-question-id"
    }
  ]
}

forms_validate は、表示される質問 ID、問題、および正確にシリアライズされた回答配列を返します。分岐によってスキップされた質問は除外されます。

仕組み

ブラウザーのブートストラップでは、偽造防止トークン、サーバーセッション ID、フォーム所有者のテナントとユーザー、回答者のテナントとユーザー、およびフォームのプリフェッチ URL が公開されます。クライアントはこのデータとスコープ設定された Forms Cookie を組み合わせて、直接リクエストを行います。

確認されたエンドポイントの種類：

GET  /formapi/api/{tenant}/users/{owner}/light/runtimeForms('{formId}')
POST /formapi/api/{tenant}/users/{owner}/forms('{formId}')/responses
POST /formapi/api/{tenant}/users/{owner}/runtimeForms('{formId}')/questions('{questionId}')/CreateUploadSession
POST /formapi/api/{ownerTenant}/users/{owner}/saveResponseLink
GET  /formapi/api/{responderTenant}/users/{responder}/getResponseLinks

正規化されたモデルには生オブジェクトが保持されるため、このパッケージで正式にサポートされる前でも、新たに導入された Forms プロパティを確認できます。

制限事項

• API は非公開であり、変更される可能性があります。
• 現在、ファイルのアップロードには、レンダリングされた分岐でアップロードの質問が表示されている必要があります。
• 認証は Microsoft Forms の Web ログイン動作に依存します。
• このパッケージは、正当なフォーム自動化を目的としています。フォーム所有者、テナントのポリシー、プライバシー要件、および適用される法律を尊重してください。

開発

CONTRIBUTING.md を参照してください。

npm install
npm run type-check
npm test
npm run format-check
npm run spell-check
npm run build

ライセンス

MIT