formio-mcp — Claude Code MCP server: Form.io forms from your agent
Wires your agent into Form.io so it can build forms, resources, actions, roles and projects from chat. Useful when the forms live in Form.io rather than in your code.
claude mcp add --env FORMIO_PROJECT_URL=<FORMIO_PROJECT_URL> --env FORMIO_BASE_URL=<FORMIO_BASE_URL> --env FORMIO_API_KEY=<FORMIO_API_KEY> --env FORMIO_LOGIN_FORM=<FORMIO_LOGIN_FORM> --env FORMIO_AUTH_HOST=<FORMIO_AUTH_HOST> --transport stdio mcp-server -- npx -y @formio/mcpWhat formio-mcp does
@formio/mcp runs over stdio. Your client launches the process and keeps its input and output streams; nothing listens on a port and you never start it by hand. HTTP and SSE are not offered at all. The one HTTP listener the server opens is a short-lived browser sign-in page, and no MCP traffic passes through it.
Every tool that talks to Form.io needs a project. Three places can supply it, and the narrower scope wins: a committed formio.json, a per-directory mapping written by the project_set tool, or the FORMIO_PROJECT_URL variable. FORMIO_BASE_URL is rarely needed — the base address follows from the shape of the project URL, and the server asks for it only when it cannot work that out. Startup does not depend on either value, so a client can connect and list tools first; the project URL is requested when a tool actually needs it, and server_status answers either way.
The Docker image formio/mcp also speaks stdio, so run the container with -i. Two things break on a private deployment. A private hostname will not resolve inside the container — map it with --add-host. And the image trusts only the standard CA bundle, so a certificate your own machine accepts still fails there with a bare fetch failed. For a certificate from a private CA, mount the root certificate and set NODE_EXTRA_CA_CERTS. A fully self-signed server certificate cannot be fixed that way: Node wants a CA as the trust anchor and rejects the chain with DEPTH_ZERO_SELF_SIGNED_CERT.
What it helps with
- build a Form.io form from a description in chat
- set up a resource and its roles for a new project
- edit a form action without opening the web UI
- point the agent at a different Form.io project
- check the Form.io connection before doing work
Example prompts for the agent
- Create a feedback form in Form.io with name, email and message fields
- Add an editor role to the current Form.io project
- Show the Form.io connection status
How to install formio-mcp
Platform CLI
claude mcp add --env FORMIO_PROJECT_URL=<FORMIO_PROJECT_URL> --env FORMIO_BASE_URL=<FORMIO_BASE_URL> --env FORMIO_API_KEY=<FORMIO_API_KEY> --env FORMIO_LOGIN_FORM=<FORMIO_LOGIN_FORM> --env FORMIO_AUTH_HOST=<FORMIO_AUTH_HOST> --transport stdio mcp-server -- npx -y @formio/mcpReplace <…> with your own values. 5 more environment variables are in the server README
Platform CLI
codex mcp add mcp-server --env FORMIO_PROJECT_URL=<FORMIO_PROJECT_URL> --env FORMIO_BASE_URL=<FORMIO_BASE_URL> --env FORMIO_API_KEY=<FORMIO_API_KEY> --env FORMIO_LOGIN_FORM=<FORMIO_LOGIN_FORM> --env FORMIO_AUTH_HOST=<FORMIO_AUTH_HOST> -- npx -y @formio/mcpReplace <…> with your own values. 5 more environment variables are in the server README
Config file
{
"mcpServers": {
"mcp-server": {
"command": "npx",
"args": [
"-y",
"@formio/mcp"
],
"env": {
"FORMIO_PROJECT_URL": "<FORMIO_PROJECT_URL>",
"FORMIO_BASE_URL": "<FORMIO_BASE_URL>",
"FORMIO_API_KEY": "<FORMIO_API_KEY>",
"FORMIO_LOGIN_FORM": "<FORMIO_LOGIN_FORM>",
"FORMIO_AUTH_HOST": "<FORMIO_AUTH_HOST>"
}
}
}
}Replace <…> with your own values. 5 more environment variables are in the server README
Config file
{
"servers": {
"mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@formio/mcp"
],
"env": {
"FORMIO_PROJECT_URL": "<FORMIO_PROJECT_URL>",
"FORMIO_BASE_URL": "<FORMIO_BASE_URL>",
"FORMIO_API_KEY": "<FORMIO_API_KEY>",
"FORMIO_LOGIN_FORM": "<FORMIO_LOGIN_FORM>",
"FORMIO_AUTH_HOST": "<FORMIO_AUTH_HOST>"
}
}
}
}Replace <…> with your own values. 5 more environment variables are in the server README
Platform CLI
gemini mcp add -e FORMIO_PROJECT_URL=<FORMIO_PROJECT_URL> -e FORMIO_BASE_URL=<FORMIO_BASE_URL> -e FORMIO_API_KEY=<FORMIO_API_KEY> -e FORMIO_LOGIN_FORM=<FORMIO_LOGIN_FORM> -e FORMIO_AUTH_HOST=<FORMIO_AUTH_HOST> mcp-server npx -y @formio/mcpReplace <…> with your own values. 5 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about formio-mcp
How do I install formio-mcp in Claude Code?
Run claude mcp add formio-mcp -e FORMIO_API_KEY=<FORMIO_API_KEY> -- npx -y @formio/mcp, replacing the API key with your own.
What does formio-mcp do?
It hands your agent Form.io tools for creating and editing forms, resources, actions, roles and projects. Because it uses stdio, any MCP client can host it.
What does the server need to work?
A Form.io project, taken from formio.json, a project_set mapping or FORMIO_PROJECT_URL. FORMIO_API_KEY is the way to sign in without a browser.
