# Formswrite MCP

Connect [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.sh), [Claude Code](https://docs.claude.com/claude-code), and other MCP clients to the [Formswrite](https://formswrite.com) API.

Convert documents to Google Forms, edit questions, list and publish forms, and run AI form assistant tools — all from your LLM.

## What you can do

Once installed, your LLM gains access to the Formswrite toolset:

- **`create_form`** — create a Formswrite job from a Google Doc, PDF, or pasted text
- **`get_form_data`** — read the current questions, options, and metadata of a form
- **`modify_questions`** — add, edit, delete, or reorder questions
- **`update_form_metadata`** — update title, description, or introduction
- **`publish_form`** — publish a draft form so it can accept responses
- **`export_form`** — export a form to Google Forms, Moodle, Kahoot, Quizizz, Canvas, and 25+ other formats
- **`list_jobs`** / **`get_job`** — browse and inspect your conversion jobs

## Install

### 1. Get an API token

Sign in to your Formswrite dashboard and create an API token at:
**https://app.formswrite.com/settings/api-tokens**

### 2. Add to your MCP client

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "formswrite": {
      "command": "npx",
      "args": ["-y", "@formswrite/mcp"],
      "env": {
        "FORMSWRITE_API_TOKEN": "fw_..."
      }
    }
  }
}
```

Restart Claude Desktop. The Formswrite tools will appear in the tools list.

#### Cursor

In **Settings → MCP**, add:

```json
{
  "formswrite": {
    "command": "npx",
    "args": ["-y", "@formswrite/mcp"],
    "env": { "FORMSWRITE_API_TOKEN": "fw_..." }
  }
}
```

#### Claude Code

```bash
claude mcp add formswrite -- npx -y @formswrite/mcp
```

Then set the token in `~/.claude/settings.json`:

```json
{ "env": { "FORMSWRITE_API_TOKEN": "fw_..." } }
```

#### Direct Streamable HTTP (no npm needed)

If your client supports the **Streamable HTTP** transport natively (Cursor 0.45+, ChatGPT MCP, recent Claude Desktop), you can skip this package and connect directly:

```
URL:    https://mcp.formswrite.com/mcp
Header: Authorization: Bearer fw_...
```

## How it works

This package is a small stdio ↔ Streamable HTTP bridge. It runs locally on your machine, opens a connection to `https://mcp.formswrite.com/mcp` using your API token, and forwards JSON-RPC messages between your MCP client (stdio) and the Formswrite server (HTTP).

All tool logic lives on the Formswrite backend — this package contains no business logic and never sees your form data outside of forwarding it.

## Configuration

| Env var                  | Required | Default                            | Description                              |
| ------------------------ | -------- | ---------------------------------- | ---------------------------------------- |
| `FORMSWRITE_API_TOKEN`   | yes      | —                                  | API token from your Formswrite dashboard |
| `FORMSWRITE_MCP_URL`     | no       | `https://mcp.formswrite.com/mcp`   | Override for staging or self-hosted      |

## Troubleshooting

Diagnostic output is written to **stderr** (stdout is the JSON-RPC channel). To see logs:

- **Claude Desktop**: open the MCP logs panel (Settings → Developer)
- **CLI**: run `FORMSWRITE_API_TOKEN=... npx @formswrite/mcp 2>&1 >/dev/null`

Common issues:

- **`Missing token`** — `FORMSWRITE_API_TOKEN` is not set in your client's MCP `env` block
- **`401 unauthorized`** — token is invalid, expired, or for the wrong environment. Generate a new one at the dashboard URL above
- **`429 rate_limited`** — you're past the 60 req/min limit; slow down

## License

MIT — see [LICENSE](./LICENSE).

## Links

- Formswrite: https://formswrite.com
- Dashboard: https://app.formswrite.com
- Issues: https://github.com/formswrite/formswrite-mcp/issues
- MCP spec: https://modelcontextprotocol.io