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.

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.

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"]}'

Add the MCP configuration above to claude_desktop_config.json.

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

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

Related MCP server: mcp-google-forms

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

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:

{
  "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:

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.

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

License

MIT