formr-mcp

A Model Context Protocol server for the formr survey framework. Let LLM agents inspect, create, and edit formr run structures, manage settings, and get design guidance — all through natural language.

Prerequisites

• Python 3.12+
• uv — fast Python package manager
• formr instance with admin (≥ 2) API access — create credentials at <base_url>/admin/account#api
• R (optional) — enables R syntax validation in analyze_run

Quick Start

git clone https://github.com/timseidel/formr-mcp && cd formr-mcp
cp .env.example .env
# Edit .env with your formr instance URL and API credentials
uv sync
uv run server.py

Environment Variables

Variable	Description
FORMR_BASE_URL	formr instance URL (e.g. http://localhost)
FORMR_CLIENT_ID	32-char hex client ID from /admin/account#api
FORMR_CLIENT_SECRET	64-char hex secret from /admin/account#api
FLOWCHART_URL	(optional) URL of the formr Flowchart Generator (default: https://formr-flowchart-test.pages.dev)

MCP Client Configuration

opencode

Add to opencode.json in your project root:

{
  "mcp": {
    "formr-mcp": {
      "type": "local",
      "command": ["uv", "run", "server.py"],
      "enabled": true
    }
  }
}

Or copy from the included example:

cp opencode.json.example opencode.json

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "formr-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/formr-mcp", "server.py"],
      "env": {
        "FORMR_BASE_URL": "http://localhost",
        "FORMR_CLIENT_ID": "your_client_id",
        "FORMR_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "formr-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/formr-mcp", "server.py"]
    }
  }
}

Set FORMR_BASE_URL, FORMR_CLIENT_ID, and FORMR_CLIENT_SECRET in a .env file in the project root.

Available Tools

Run Management

Tool	Description
list_runs	List all runs, optionally filter by name
get_run	Get run metadata by exact name
create_run	Create a new empty run
delete_run	Permanently delete a run and all its data
whoami	Get the authenticated user's profile

Structure Editing

Tool	Description
get_run_structure_to_file	Fetch full structure to .formr/<name>.json (backs up existing)
update_run_structure_from_file	Validate and upload from .formr/<name>.json
update_run_settings	Change run-level settings (title, visibility, etc.)

Inspection & Analysis

Tool	Description
summarize_run	Human-readable overview (detail="units" or "items")
find_run_items	Search items by name/label substring and/or type
analyze_run	Check R syntax, variable refs, branch flow, item consistency
open_flowchart	Upload run structure and get a shareable flowchart URL (expires in 24h)

Documentation

Tool	Description
get_documentation	Learn formr design (topics: item-types, run-concepts, r-code, survey-json, examples, best-practices)
get_unit_types	Get all supported unit types and their required/optional fields
get_documentation_topics	List available documentation topics

Structure Editing Workflow

Run structures can be large. Use the file-based workflow instead of passing JSON through tool arguments:

1. Fetch   get_run_structure_to_file("my-run")
           → writes .formr/my-run.json

2. Edit    Use your editor/agent to modify .formr/my-run.json

3. Upload  update_run_structure_from_file("my-run")
           → validates, uploads, removes backup on success

• If .formr/my-run.json already exists, the previous version is backed up to .formr/my-run.json.bak
• On upload validation errors, fix the file and retry — restore from .bak if stuck
• The .formr/ directory is gitignored

Project Structure

formr-mcp/
├── server.py                  # MCP server entry point, tool definitions
├── formr_mcp/
│   ├── auth.py                # OAuth2 client credentials flow
│   ├── client.py              # HTTP client for formr REST API
│   ├── documentation.py       # Built-in design documentation topics
│   ├── analysis.py            # Run structure analysis (R syntax, refs, flow)
│   ├── summarize.py           # Run summarization and item search
│   └── validation.py          # Structure validation (types, positions, choices)
├── tests/
│   ├── test_server.py         # Server and tool tests
│   ├── test_analysis.py       # Analysis module tests
│   ├── test_summarize.py       # Summarization tests
│   └── test_normalize_choices.py # Choice normalization tests
├── .env.example               # Environment variable template
├── opencode.json.example      # opencode MCP config template
└── pyproject.toml             # Project metadata and dependencies

Testing

uv run --with pytest pytest tests/

Data Protection

This server interacts with the formr admin API only. It accesses run structures, survey definitions, and settings — never participant response data. Runs are fetched and edited as structural JSON, not as data exports.

License

MIT