Fillout MCP Server

🚀 Fillout.io MCP Server

An MCP server for the Fillout.io API, supporting form management, response handling, and analysis.

🚀 Quick Start

Token Setup

1. Obtain your Fillout.io API key:

   • Log in to your Fillout.io account.
   • Navigate to Account Settings → API and 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 are only applicable to test forms.
   • API keys provide access to all resources in your account.

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

⚠️ Important Note

• Keep your API key secure and private.
• Use test keys for development.
• Store keys in environment variables.
• Avoid hard - coding keys in your code.
• Regularly update and rotate keys.

Troubleshooting

Common Errors and Solutions:

1. Invalid API Key

   • Ensure the key is correct.
   • Check for case - sensitivity (the API may be case - sensitive).
   • Confirm that the key has not expired.

2. Network Connectivity Issues

   • Check if the network is working properly.
   • Ensure that the API service endpoint is reachable.
   • Use a packet - capturing tool to check requests and responses.

3. Insufficient Permissions

   • Confirm that the key has the required permissions.
   • Contact the administrator to check the key permission settings.
   • Refer to the API documentation to confirm if the operation requires additional permissions.

4. Rate Limiting

   • Wait for some time and then retry.
   • Use queuing or rate - limiting mechanisms.
   • Contact support to increase your quota.

✨ Features

• Form Management: Create, read, update, and delete forms.
• Response Handling: Submit, retrieve, modify, and delete response data.
• User Authentication: Integrate multiple authentication methods.
• Data Analysis: Statistically analyze form filling status.
• Event Triggering: Configure custom actions after form completion.

📦 Installation

Installation and Execution

# Install dependencies
npm install

# Start in development mode
npm run dev

# Build the production version
npm run build

Docker Deployment

# Build the image
docker build -t mcp/fillout .

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

Build Requirements

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

💻 Usage Examples

Basic Usage

Create a Form

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

Submit a Response

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

Error Handling

The server provides detailed error messages to handle common issues:

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

📄 License

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