Danielma Tic Fillout MCP Server

🚀 Fillout.io MCP Server

The MCP server for the Fillout.io API, enabling 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 Webhook.
   • 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.
3. Configure environment variables:

   FILLOUT_API_KEY=Your Fillout.io API key
   

💻 Troubleshooting

Here are common issues and their solutions:

1. Invalid API Key

• Symptom: The API request returns an "unauthorized" error.
• Cause: The key used is incorrect or has been disabled.
• Solution:
  • Confirm if the key is correct.
  • Check the key status (enabled/disabled).

2. Exceeding Rate Limit

• Symptom: The API request returns a "too many requests" error.
• Cause: Too many requests are made in a short period.
• Solution:
  • Wait for some time and try again.
  • Upgrade your API usage plan.

✨ Features

Form Management

• Create forms
• Update forms
• Delete forms
• List all forms

Response Handling

• Submit responses
• Get specific responses
• Delete responses
• Export response data

Analysis

• Generate reports
• View statistics
• Set up custom analysis

🛠️ Tools

Local Development Configuration

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

Docker Configuration

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

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

💻 Usage Examples

Basic Usage

Create a Form

const form = await client.createForm({
  name: "Customer Feedback",
  description: "Please 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: "Great customer service!"
    },
    {
      questionId: "q2",
      value: "Yes"
    }
  ]
});

🛠️ Error Handling

The server provides detailed error messages to help diagnose 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. For more details, please refer to the LICENSE file.