# formio-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/formio/ai  
**GitHub Stars:** 8  
**npm Downloads (last month):** 2778  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/formio-mcp

## Description
Create and manage Form.io forms, resources, actions, roles, and projects from your AI agent.

## Tools
Capabilities this server exposes over MCP:

- **hello** — Say hello — a connectivity check that confirms the server is running and reachable. Needs no Form.io project or credentials, so it is the first thing to try when other tools fail.
- **form_create** — Create a new form in the Form.io project mapped to the user's current working directory. IMPORTANT: Before calling this tool, use the formio-schema skill to construct a properly structured Form.io form JSON definition based on the user's requirements. The skill documents all component types, validation options, layout patterns, and conditional logic available in Form.io. New forms default to `revisions: 'original'` so form change history is preserved. NOT for: creating a draft revision of an existing form. When the user says "create/save a draft", "draft <change>", call form_update with `formId` and `draft: true` instead.
- **form_get** — Fetch a single form definition from the Form.io project mapped to the user's current working directory, by form ID or path. Pass `draft: true` to fetch the form's current in-flight draft instead of the published form.
- **form_list** — List forms from the Form.io project mapped to the user's current working directory with optional filtering and pagination.
- **form_revision_get** — Fetch a single immutable form revision from the Form.io project mapped to the current working directory. `version` accepts either the revision `_vid` (e.g. "3") or the revision document `_id` (24-character hex). To revert the live form to this revision, pass its `form` body to `form_update` with a `note` like `Revert to v<vid>`.
- **form_revisions_list** — List immutable published revision summaries for a single form in the Form.io project mapped to the current working directory. Returns compact revision metadata (_vid, _id, modified, user, _vnote) for the form identified by `formIdOrPath`. To inspect a specific revision body, call `form_revision_get` with the desired `_vid`. To revert the live form to a prior revision, pass that revision body to `form_update` with a `note` like `Revert to v<vid>`.
- **form_update** — Update an existing form in the Form.io project mapped to the user's current working directory. IMPORTANT: Before calling this tool, first use form_get to fetch the current form definition, then use the formio-schema skill to understand the schema so that you can apply the requested modifications (add, remove, or modify fields and settings), and finally call this tool with the complete updated form JSON. `draft`, `publish`, and `revert` are mutually exclusive — pass at most one. If `revisions` in the response differs from the stored value, the per-form revisions-mode gate prompted the USER and they chose.
- **project_export** — Export the complete template (roles, resources, forms, actions) of the Form.io project mapped to the user's current working directory as a portable JSON document. Use this to snapshot a project before importing changes.
- **project_get** — Report which Form.io project the given working directory resolves to, which deployment hosts it, and which layer supplied each — the preflight to run before the first tool call that reads from or writes to a deployment. Answers from inside this server, using the same resolver every other tool uses, so what it reports is what the next call targets. There is no need to run any shell command to ask this. Branch on `status`. "ok" means both URLs resolved and you may proceed. "not-configured" means nothing is mapped for this directory: relay the message, ask the user for the single value it names, record it with project_set, and call this again. "base-url-unresolved" means the project IS recorded and only its deployment is missing — ask for the Base URL alone and do NOT re-ask for the Project URL. Reads only. It resolves and reports; project_set is what records a choice.
- **project_import** — Import a template JSON into the existing Form.io project mapped to the user's current working directory, merging roles, resources, forms, and actions in one call. Use the formio-resource-planner skill to construct the template before calling this tool. WARNING: import merges into the existing project — use project_export first to snapshot.
- **project_set** — Set the active Form.io project for the given working directory by recording its URL in ~/.formio/projects.json You MUST call this tool whenever the user asks to set, change, or switch the active Form.io project — do not merely acknowledge the request in text. Persisting the choice requires the tool call. The chosen URL is persisted to ~/.formio/projects.json keyed by the cwd argument when provided (or the MCP server process cwd otherwise). Pass the `cwd` argument whenever you know the user's current working directory — the server process cwd is fixed at spawn and may not match where the user actually is. Every Form.io tool resolves its project on each call, so a mapping written here needs no restart. It takes effect only where the mapping is the record that WINS, though: under a committed formio.json the mapping is the fallback if that file goes away, and this call reports the pair that actually resolves rather than the one it recorded. Read `ok` and `projectUrl` on the result rather than assuming the write governs. You normally pass only projectUrl. The base URL — which builds the portal-login URL and keys the cached token — is derived from it — https://api.form.io for a project on a form.io host, and the parent path for a project addressed as a sub-directory — so there is nothing to supply. Pass baseUrl ONLY when the server reports that it cannot be determined, which happens for a project URL that carries no path on a customer domain: there the deployment is a sibling sub-domain and nothing in the project URL names it. Do not ask the user for a base URL before the server says it needs one. This tool writes the machine-local mapping, which is keyed by absolute path and therefore does not survive a clone. To record the target with the code instead — versioned, visible in a diff, and shared with everyone who clones the repository — write a committed formio.json yourself, in the application's own folder: a JSON object holding {"projectUrl": "..."}, plus "baseUrl" only when it cannot be derived. This server reads that file and never writes it. Resolution is by scope, narrowest first, and precedence runs: a committed formio.json, then the working-directory mapping, then FORMIO_PROJECT_URL in the environment, which is the weakest of the three. So a mapping written here DOES override an environment value, and a committed file overrides both.
- **role_create** — Create a new role in the Form.io project mapped to the user's current working directory.
- **role_list** — List all roles defined in the Form.io project mapped to the user's current working directory.
- **role_update** — Update an existing role in the Form.io project mapped to the user's current working directory. This is a full replacement — include all fields you want to preserve.
- **action_types_list** — List available action types for a form. Returns the catalog of action types the server supports.
- **action_type_get** — Get action type info and settings form schema. Call this before action_create to discover the required settings for the action type.
- **action_create** — Create a new action on a form. Call action_type_get first to discover the required settings schema for the action type.
- **action_list** — List the actions configured on a form — the server-side handlers that run when a submission is saved, such as save-to-resource, email, login, and role assignment.
- **action_get** — Get a single action by ID from a form, including its handler, method, condition, and type-specific settings. Call action_list first to find the action ID.
- **action_update** — Update an existing action on a form. This is a full replacement of the action document — include every field you want to keep, and call action_get first if you do not already have it.
- **action_delete** — Delete an action from a form. The action stops running on submissions immediately and is not recoverable — call action_get first if the settings may be needed again.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "formio-mcp": {
    "command": "npx",
    "args": ["-y","@formio/mcp@0.14.1"]
  }
}
```

## Documentation

## What formio-mcp MCP server does

The formio-mcp MCP server exposes Form.io Enterprise Server operations to MCP-compatible AI coding environments. Its tool groups cover forms, roles, actions, projects, and diagnostics. The repository also describes operations for Form.io resources, allowing an agent to work with the application data model alongside form definitions and related configuration.

The server is intended for projects built on Form.io. An agent can use tools such as `form_create`, `form_list`, and `project_import`, while the broader toolset is organized around `form_*`, `role_*`, `action_*`, and `project_*` operations. The repository presents this as a way to build complete applications with Form.io-managed data models, forms, workflows, and business logic.

## How it works

The formio-mcp MCP server is installed as the `@formio/mcp` package and connected to an agentic coding client through MCP. The repository also provides `@formio/ai`, which bundles the MCP server with a skills library for coding agents. Skills can guide workflows such as form building, wizard creation, form embedding, resource planning, authentication and authorization, and use of the Form.io JavaScript SDK.

Project resolution is scoped to the working directory. The server can read a committed `formio.json` file containing a `projectUrl`, or use a per-directory record managed through the command line. The project URL identifies the Form.io project endpoint. A base URL can be derived in common deployment layouts, while some self-hosted subdomain deployments require it to be supplied explicitly.

## Setup and configuration

The skills library can be installed with `npx skills add formio/ai`. This installs skills into `.agents/skills/`; the bundled setup skill can then write the MCP configuration for the selected client. The repository also documents a Claude Code plugin installation that includes both the skills and the MCP server.

For direct project setup, the package provides commands such as `project get` and `project set`. A typical setup records a project URL for the current directory. Alternatively, placing `formio.json` in the application directory makes the project setting shareable with the codebase; the server reads this file and does not write to it. `project set --reset` removes the local directory record.

Self-hosted deployments may need both a project URL and a base URL. The documented `--force` option is intended for a specific deployment pairing and is available to the shell command, not to the `project_set` MCP tool.

## Tools and capabilities

- Create and list Form.io forms.
- Manage Form.io resources, roles, and actions.
- Import and configure projects through project tools.
- Inspect project resolution with diagnostic and project operations.
- Use agent skills for form building, wizards, embedding, and related application workflows.

## Limitations and notes

The README identifies the target backend as Form.io Enterprise Server; it does not describe this package as a general-purpose form service for unrelated backends. Project URL and deployment routing must resolve correctly before project-dependent operations can work. SaaS projects use `https://api.form.io` as the base URL, while self-hosted routing can require different configuration.

The repository lists Cursor, Codex, and Copilot plugin installation as coming soon in its agent plugin section. The MCP package itself is described as usable with MCP-aware clients, but client-specific setup details are not provided for every client.

_Full upstream README: https://allmcps.com/mcp/formio-mcp/readme_