msforms-api

AI-native Microsoft Forms automation for inspecting forms, resolving branching, validating answers, uploading files, submitting responses, and saving response links.

Use it as:

1. MCP server for AI agents and editors — recommended for most users.
2. Agent skill backed by the CLI for agents that can run shell commands.
3. CLI for scripts and terminal workflows.
4. TypeScript SDK for custom applications.

[!NOTE] This project was generated by GitHub Copilot App using GPT-5.6 Sol with Extra High reasoning in Autopilot mode.

[!WARNING] This project uses reverse-engineered Microsoft Forms web APIs. Microsoft does not document or guarantee these endpoints. They can change without notice. This project is not affiliated with or endorsed by Microsoft.

Quick start

Prerequisites

• Node.js 22 or later.
• Google Chrome or Microsoft Edge. Playwright Chromium is installed automatically when neither is available.

Install as an agent skill

The CLI skill teaches agents how to inspect branching, prepare and validate answers, upload authorized files, and require explicit approval before submission:

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

The installer detects supported agents such as Claude Code, Cursor, GitHub Copilot, and Codex, then asks where to install the skill. Choose global scope to use it across projects.

The skill runs msforms-api through npx, so it does not require a global package installation or MCP configuration. It is an alternative interface to the MCP server; both use the same CLI and SDK behavior.

Install in an AI tool

Click an install badge above, or use this MCP configuration. For Cursor, save it as ~/.cursor/mcp.json:

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

On first use, ask your agent to authenticate Microsoft Forms. A browser opens for sign-in, then future operations reuse the persistent session.

Try:

Inspect this Microsoft Form and explain every question, validation, upload rule, and branch: https://forms.cloud.microsoft/...

The agent can prepare and validate answers without submitting. Submission uses a separate destructive MCP tool and requires explicit confirmation.

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

What agents can do

• Read complete form metadata, including raw API objects.
• Understand question types, options, required state, and text validation.
• Resolve choice branching through stable question identifiers.
• Inspect matrix rows and their shared options.
• Inspect file count, size, and extension restrictions.
• Validate and serialize answers without submitting.
• Upload files through the authenticated Forms frontend.
• Submit only after explicit confirmation.
• Save and list response links in the signed-in account.

MCP tools

forms_submit is marked destructive and non-idempotent. It uses MCP v2 multi-round-trip elicitation. Declined or false confirmation never reaches submission code.

Cross-cutting workflow and safety guidance is also available through:

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

CLI

Run without installing globally:

# 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

Frequent CLI users can install globally:

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

Every command emits JSON. Add --compact for single-line output.

Authentication and local data

Authentication opens a visible browser and stores its profile under:

~/.msforms-api/browser-profile

The SDK uses that profile to obtain scoped Forms cookies, an anti-forgery token, and session metadata. It does not print or return those credentials. Normal reads and submissions use direct Forms HTTP requests. File upload is browser-assisted because the Forms frontend manages SharePoint authorization.

Override the profile or browser:

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

MCP environment variables:

Delete ~/.msforms-api/browser-profile to remove the local session.

Answer format

Answers are keyed by exact question ID returned from forms_inspect.

Matrix answers use each row question ID, not the matrix group 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",
};

Read the full README on GitHub →