Fillout.io MCP Server: Automate Workflows & Drive Data Insights

Fillout.io MCP Server

MCP Server for the Fillout.io API, enabling form management, response handling, and analytics.

Token Setup

1. Get your Fillout.io API Key:

* Log in to your Fillout.io account
* Go to Account Settings → API & Webhooks
* Click "Create new API Key"
* Copy your new API key

2. API Key Information:

* Production keys start with `fo_live_`
* Test keys start with `fo_test_`
* Test keys only work with test forms
* API keys provide access to all resources in your account

3. Replace your-fillout-api-key in the configuration with your API key.

⚠️ Security Notes:

• Keep your API key secure and private
• Use test keys for development
• Store keys in environment variables
• Rotate keys periodically
• Never commit keys to version control

Token Troubleshooting

Common Error Messages

1. "Invalid API key provided" or "Authentication failed"

* **Cause** : API key is missing, malformed, or invalid
* **Solution** : 
  * Verify key starts with `fo_live_` or `fo_test_`
  * Check for extra spaces or characters
  * Ensure environment variable is set correctly
  * Create a new key if necessary

2. "Test mode key used with live form"

* **Cause** : Using test key (`fo_test_`) with production form
* **Solution** : 
  * Use live key for production forms
  * Create test form for development
  * Switch to appropriate key type

3. "Rate limit exceeded"

* **Cause** : Too many API requests
* **Solution** : 
  * Implement request throttling
  * Check usage in dashboard
  * Optimize request patterns

Validation Steps

1. Check API Key Format:

   Key should:

- Start with 'fo_live_' or 'fo_test_'
- Be approximately 50 characters
- Contain only letters, numbers, and underscores

2. Test API Key:

   curl -H "Authorization: Bearer your-api-key"
   https://api.fillout.com/v1/api/forms

Features

Form Management

• List all forms
• Get form details
• Create new forms
• Delete forms
• Update form settings

Response Handling

• Submit form responses
• Get form submissions
• Filter responses
• Export responses

Analytics

• Response rates
• Completion times
• Submission trends

Tools

1. list_forms

* Get all accessible forms
* Parameters: 
  * `limit` (optional): Number of forms to return
  * `offset` (optional): Pagination offset
* Returns: Array of form objects

2. get_form

* Get detailed form information
* Parameters: 
  * `formId` (string): Form identifier
* Returns: Form details including questions and settings

3. create_form

* Create a new form
* Parameters: 
  * `name` (string): Form name
  * `description` (optional string): Form description
  * `questions` (array): Array of question objects 
    * `type`: Question type (e.g., 'ShortAnswer', 'MultipleChoice')
    * `name`: Question text
    * `required`: Whether question is required
    * `choices`: Array of choices for multiple choice questions
* Returns: Created form object

4. get_form_responses

* Get form submissions
* Parameters: 
  * `formId` (string): Form identifier
  * `filters` (optional): Response filters
  * `pageSize` (optional): Results per page
  * `afterDate` (optional): Filter by submission date
  * `beforeDate` (optional): Filter by submission date
  * `status` (optional): Filter by completion status
* Returns: Array of form responses

5. submit_form_response

* Submit a new response
* Parameters: 
  * `formId` (string): Form identifier
  * `responses` (array): Array of answers 
    * `questionId`: Question identifier
    * `value`: Response value
  * `calculations` (optional): Custom calculations
* Returns: Submission confirmation

Setup

Usage with Claude Desktop

Docker Configuration

{
  "mcpServers": {
    "fillout": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "FILLOUT_API_KEY",
        "mcp/fillout"
      ],
      "env": {
        "FILLOUT_API_KEY": "your-fillout-api-key"
      }
    }
  }
}

NPX Configuration

{
  "mcpServers": {
    "fillout": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fillout"
      ],
      "env": {
        "FILLOUT_API_KEY": "your-fillout-api-key"
      }
    }
  }
}

Building

Prerequisites

• Node.js 18 or later
• npm or yarn
• Docker (optional)

Local Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

Docker Build

# Build image
docker build -t mcp/fillout .

# Run container
docker run -e FILLOUT_API_KEY=your-key mcp/fillout

Examples

Creating a Form

const form = await client.createForm({
  name: "Customer Feedback",
  description: "Please share your experience",
  questions: [
    {
      type: "ShortAnswer",
      name: "What did you like most?",
      required: true
    },
    {
      type: "MultipleChoice",
      name: "Would you recommend us?",
      required: true,
      choices: ["Yes", "No", "Maybe"]
    }
  ]
});

Submitting a Response

const response = await client.submitFormResponse(formId, {
  responses: [
    {
      questionId: "q1",
      value: "Great customer service!"
    },
    {
      questionId: "q2",
      value: "Yes"
    }
  ]
});

Error Handling

The server provides detailed error messages for common issues:

try {
  const forms = await client.listForms();
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Handle invalid API key
  } else if (error instanceof FilloutError) {
    // Handle API-specific errors
  } else {
    // Handle unexpected errors
  }
}

License

This project is licensed under the MIT License. See the LICENSE file for details.