Fillout.io MCP 服务器

Fillout.io API 的 MCP 服务器，支持表单管理、响应处理和分析。

令牌设置

1. 获取您的 Fillout.io API 密钥：

   • 登录您的 Fillout.io 帐户

   • 前往账户设置 → API 和 Webhook

   • 点击“创建新的 API 密钥”

   • 复制您的新 API 密钥

2. API密钥信息：

   • 生产密钥以fo_live_开头

   • 测试键以fo_test_开头

   • 测试键仅适用于测试表单

   • API 密钥提供对您帐户中所有资源的访问权限

3. 将配置中的your-fillout-api-key替换为您的 API 密钥。

⚠️ 安全注意事项：

• 确保您的 API 密钥的安全和私密性

• 使用测试密钥进行开发

• 将密钥存储在环境变量中

• 定期轮换密钥

• 永远不要将密钥提交到版本控制

Related MCP server: Loxo MCP Server

令牌故障排除

常见错误消息

1. “提供的 API 密钥无效”或“身份验证失败”

   • 原因：API 密钥缺失、格式错误或无效

   • 解决方案：

     • 验证密钥是否以fo_live_或fo_test_开头

     • 检查是否有多余的空格或字符

     • 确保环境变量设置正确

     • 如果需要，创建新密钥

2. “与实时表单一起使用的测试模式键”

   • 原因：使用测试键（ fo_test_ ）和生产表单

   • 解决方案：

     • 使用实时密钥来制作表格

     • 创建开发测试表单

     • 切换到适当的键类型

3. “超出速率限制”

   • 原因：API 请求过多

   • 解决方案：

     • 实施请求限制

     • 在仪表板中检查使用情况

     • 优化请求模式

验证步骤

1. 检查 API 密钥格式：

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

2. 测试 API 密钥：

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

特征

表单管理

• 列出所有表格

• 获取表单详细信息

• 创建新表单

• 删除表单

• 更新表单设置

响应处理

• 提交表单回复

• 获取表单提交

• 过滤响应

• 导出响应

分析

• 回复率

• 完成时间

• 投稿趋势

工具

1. list_forms

   • 获取所有可访问的表单

   • 参数：

     • limit （可选）：要返回的表单数量

     • offset （可选）：分页偏移量

   • 返回：表单对象数组

2. get_form

   • 获取详细的表单信息

   • 参数：

     • formId （字符串）：表单标识符

   • 返回：表单详细信息，包括问题和设置

3. create_form

   • 创建新表单

   • 参数：

     • name （字符串）：表单名称

     • description （可选字符串）：表单描述

     • questions （数组）：问题对象数组

       • type ：问题类型（例如，“简答题”、“多项选择题”）

       • name ：问题文本

       • required ：问题是否必填

       • choices ：多项选择题的选项数组

   • 返回：创建的表单对象

4. get_form_responses

   • 获取表单提交

   • 参数：

     • formId （字符串）：表单标识符

     • filters （可选）：响应过滤器

     • pageSize （可选）：每页结果数

     • afterDate （可选）：按提交日期过滤

     • beforeDate （可选）：按提交日期过滤

     • status （可选）：按完成状态过滤

   • 返回：表单响应数组

5. submit_form_response

   • 提交新的回复

   • 参数：

     • formId （字符串）：表单标识符

     • responses （数组）：答案数组

       • questionId ：问题标识符

       • value ：响应值

     • calculations （可选）：自定义计算

   • 返回：提交确认

设置

与 Claude Desktop 一起使用

Docker 配置

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

NPX 配置

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

建筑

先决条件

• Node.js 18 或更高版本

• npm 或 yarn

• Docker（可选）

本地开发

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

Docker 构建

# Build image
docker build -t mcp/fillout .

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

示例

创建表单

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"]
    }
  ]
});

提交回复

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

错误处理

服务器提供了常见问题的详细错误消息：

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
  }
}

执照

本项目遵循 MIT 许可证。详情请参阅 LICENSE 文件。