# formslist-mcp

MCP (Model Context Protocol) server for [FormsList](https://formslist.com) — a form-backend SaaS. Point any HTML form at a FormsList endpoint and it handles submissions, email notifications, spam filtering, auto-responses, and analytics with no server code.

This server lets any MCP client (Claude Code, Claude Desktop, Cursor, ...) create form endpoints, read submissions, configure auto-responses, and generate embed snippets.

## Tools

| Tool | API key? | What it does |
| --- | --- | --- |
| `instant_provision` | No | Create a working form endpoint instantly for any email — no account needed. The owner claims it later via the returned `claim_url`. Also returns a ready-to-paste `html_snippet` and `curl_example`. |
| `create_form` | Yes | Create a new form (`name`, optional `description`). |
| `list_forms` | Yes | List all forms in the account. |
| `get_form` | Yes | Get one form's details by `form_id`. |
| `get_submissions` | Yes | Get a form's submissions (`page`, `per_page` pagination). |
| `configure_autoresponse` | Yes | Enable/configure the auto-response email (`enabled`, `subject`, `body_html`, `from_name`). If the plan doesn't include auto-responses, the tool returns the upgrade message and `upgrade_url` instead of erroring. |
| `get_embed_snippet` | No | Pure local generator: builds an HTML `<form>` snippet + AJAX example that posts to `https://formslist.com/f/<hash>`. |

**`instant_provision` and `get_embed_snippet` work with zero config** — no API key needed.

The API key (`ff_sk_...`) is created at <https://formslist.com/account/api-keys> and passed via the `FORMSLIST_API_KEY` environment variable. `FORMSLIST_BASE_URL` overrides the API base (default `https://formslist.com`).

## Install (until npm publish)

```bash
git clone <this-repo>
cd formflow/mcp
npm install
npm run build
```

The built server is at `dist/index.js`.

## Configure your MCP client

### Claude Code

```bash
claude mcp add formslist -e FORMSLIST_API_KEY=ff_sk_xxx -- npx -y formslist-mcp
```

(Omit `-e FORMSLIST_API_KEY=...` if you only need `instant_provision` / `get_embed_snippet`.)

### Claude Desktop

Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "formslist": {
      "command": "npx",
      "args": ["-y", "formslist-mcp"],
      "env": {
        "FORMSLIST_API_KEY": "ff_sk_xxx"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "formslist": {
      "command": "npx",
      "args": ["-y", "formslist-mcp"],
      "env": {
        "FORMSLIST_API_KEY": "ff_sk_xxx"
      }
    }
  }
}
```

## Notes

- Transport is stdio; all HTTP uses the global `fetch` (Node 18+).
- Non-2xx API responses are returned to the agent as `{status, error}` text — never unhandled exceptions.
- LLM-oriented product docs: <https://formslist.com/llms.txt>