# Microsoft Forms API **Category:** 💻 Developer Tools **Repository:** https://github.com/Maxim-Mazurok/msforms-api **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/microsoft-forms-api ## Description Inspect, validate, upload, and submit Microsoft Forms responses ## Claude Desktop Quick Installation Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "microsoft-forms-api": { "command": "npx", "args": ["-y","microsoft-forms-api"] } } ``` ## Documentation & README # 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. [Install in VS Code](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522microsoft-forms%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522-p%2522%252C%2522msforms-api%2540latest%2522%252C%2522msforms-api-mcp%2522%255D%257D) [Install in VS Code Insiders](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522microsoft-forms%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522-y%2522%252C%2522-p%2522%252C%2522msforms-api%2540latest%2522%252C%2522msforms-api-mcp%2522%255D%257D) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=microsoft-forms&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi1wIiwibXNmb3Jtcy1hcGlAbGF0ZXN0IiwibXNmb3Jtcy1hcGktbWNwIl19) [![npm version](https://img.shields.io/npm/v/msforms-api?style=flat-square)](https://www.npmjs.com/package/msforms-api) [![CI](https://img.shields.io/github/actions/workflow/status/Maxim-Mazurok/msforms-api/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/Maxim-Mazurok/msforms-api/actions/workflows/ci.yml) > [!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](https://nodejs.org/) 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](https://github.com/Maxim-Mazurok/msforms-api/blob/HEAD/SKILL.md) teaches agents how to inspect branching, prepare and validate answers, upload authorized files, and require explicit approval before submission: ```bash 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`: ```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.
VS Code CLI installation macOS / Linux: ```bash code --add-mcp '{"name":"microsoft-forms","command":"npx","args":["-y","-p","msforms-api@latest","msforms-api-mcp"]}' ``` Windows PowerShell: ```powershell code --add-mcp '{"name":"microsoft-forms","command":"npx","args":["-y","-p","msforms-api@latest","msforms-api-mcp"]}' ```
Claude Desktop Add the MCP configuration above to `claude_desktop_config.json`.
Claude Code ```bash claude mcp add microsoft-forms -- npx -y -p msforms-api@latest msforms-api-mcp ```
Windsurf and other MCP clients Add the MCP configuration above to your client's MCP configuration file.
## 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: ```bash npx -y -p msforms-api@latest msforms-api guide ``` ## CLI Run without installing globally: ```bash # 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: ```bash 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: ```text ~/.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: ```bash 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. ```json { "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 ```bash npm install msforms-api ``` ```ts 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()` is direct at SDK level. Applications using the SDK must implement their own user confirmation boundary. CLI requires `--confirm`; MCP requires elicitation. `submissionStatus: "submitted"` or a returned `responseId` means the permanent response exists. A requested response-link save can fail independently. In that case, `saveResponseStatus` is `"failed"`, submission details remain in the result, and callers must not submit again. Retry only the idempotent `saveResponse()` operation. ## 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: ```json { "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, form-owner tenant and user, responder tenant and user, and form prefetch URL. The client combines that data with scoped Forms cookies for direct requests. Observed endpoint families: ```text 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 ``` 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](https://github.com/Maxim-Mazurok/msforms-api/blob/HEAD/CONTRIBUTING.md). ```bash npm install npm run type-check npm test npm run format-check npm run spell-check npm run build ``` ## License [MIT](https://github.com/Maxim-Mazurok/msforms-api/blob/HEAD/LICENSE)