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.

<img src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code"> <img src="https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code Insiders">

[!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.

<details> <summary><strong>VS Code CLI installation</strong></summary>

macOS / Linux:

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

Windows PowerShell:

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

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

Add the MCP configuration above to claude_desktop_config.json.

</details>

<details> <summary><strong>Claude Code</strong></summary>

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

</details>

<details> <summary><strong>Windsurf and other MCP clients</strong></summary>

Add the MCP configuration above to your client's MCP configuration file.

</details>

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

Tool	Behavior
forms_authenticate	Opens visible browser login
forms_inspect	Returns normalized and raw form structure
forms_validate	Resolves branches and validates without submitting
forms_upload_file	Uploads a local file and returns answer metadata
forms_submit	Creates a response after elicited confirmation
forms_save_response	Saves an existing response link
forms_list_saved_responses	Lists saved response links

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:

Variable	Purpose
MSFORMS_PROFILE_DIRECTORY	Persistent browser profile override
MSFORMS_BROWSER_CHANNEL	chrome or msedge
MSFORMS_HEADLESS	Set to false to show operational browser windows

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

Answer format

Answers are keyed by exact question ID returned from forms_inspect.

Question type	Input
Text	String
Single choice	Option label or ID
Multiple choice	Array of option labels or IDs
Date	YYYY-MM-DD string
Rating or NPS	Number
Ranking	Ordered array containing every option label or ID
Matrix row	Option label, or { "id": ..., "key": ... }
File upload	Array of objects returned by forms_upload_file

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",
};

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,
});

submitResponse() is direct at SDK level. Applications using the SDK must implement their own user confirmation boundary. CLI requires --confirm; MCP requires elicitation.

Form structure

The normalized form model includes:

• IDs, titles, subtitles, order, type, and required state.
• Choice labels and branchTargetId values.
• Matrix rows with inherited options.
• Text validation boundaries and rules.
• File upload restrictions.
• Parsed form settings.
• Full raw form and question objects for forward compatibility.

Example branch:

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

forms_validate returns visible question IDs, issues, and the exact serialized answer array. Questions skipped by branching are omitted.

How it works

Browser bootstrap exposes the anti-forgery token, server session ID, tenant, owner, current user, and form prefetch URL. The client combines that data with scoped Forms cookies for direct requests.

Observed endpoint families:

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/{tenant}/users/{user}/saveResponseLink
GET  /formapi/api/{tenant}/users/{user}/getResponseLinks

The normalized model retains raw objects so newly introduced Forms properties remain inspectable before this package adds first-class support.

Limitations

• APIs are private and may change.
• File upload currently requires the upload question to be visible in the rendered branch.
• Authentication depends on Microsoft Forms web login behavior.
• The package is for legitimate form automation. Respect form owners, tenant policies, privacy requirements, and applicable law.

Development

See CONTRIBUTING.md.

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

License

MIT