Tally MCP Server

🚀 Tally MCP Server

Tally MCP Server 是一个全面的模型上下文协议（MCP）服务器，专为 Tally 表单管理而设计。该服务器提供 23 种强大的工具，可直接通过 Claude Desktop 管理表单、提交记录、问题、Webhook 和企业级条件逻辑。

由 @cathrynlavery 构建 | 试用 Claude Desktop | 获取 Tally 表单

✨ 主要特性

• 23 种综合工具：可对 Tally 表单进行全面管理。
• 企业级条件逻辑：具备关键错误预防机制。
• 高级表单构建：提供块类型文档和模板。
• 表单模板：适用于常见用例（如联系表单、调查问卷、注册表单等）。
• 完整的块类型参考：涵盖 20 多种输入、布局和逻辑块。
• 关键验证工具：防止破坏调查的逻辑错误。
• 动态问题管理：可处理复杂的条件选项集。
• 完整的 API 覆盖：包括高级表单编辑功能。
• 通过 MCP 协议与 Claude Desktop 无缝集成。
• 类型安全：具备适当的 JSON 模式验证。
• 生产就绪：具备错误处理和日志记录功能。

🚀 快速开始

前提条件

1. Node.js（v16 或更高版本）
2. Claude Desktop 应用程序
3. 具备 API 访问权限的 Tally 账户

1. 安装

git clone https://github.com/cathrynlavery/tally-mcp-server.git
cd tally-mcp-server
npm install
npm run build

2. 获取 Tally API 密钥

1. 注册 Tally 账户（免费账户即可）。
2. 访问 https://tally.so/settings/api。
3. 创建一个新的 API 密钥。
4. 复制 API 密钥（以 tally_ 开头）。

3. 配置环境变量

# 复制示例环境文件
cp .env.example .env

# 编辑 .env 文件并添加你的 API 密钥
TALLY_API_KEY=tally_your_actual_api_key_here

4. 配置 Claude Desktop

macOS 设置

1. 打开 Claude Desktop 配置文件：

   # 如果目录不存在，则创建该目录
   mkdir -p ~/Library/Application\ Support/Claude
   
   # 打开配置文件（如果不存在则创建）
   open ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. 添加 Tally MCP 服务器配置：

   {
     "mcpServers": {
       "tally": {
         "command": "node",
         "args": ["/path/to/your/tally-mcp-server/start-server.js"],
         "env": {
           "TALLY_API_KEY": "tally_your_actual_api_key_here"
         }
       }
     }
   }
   

   重要提示：请将 /path/to/your/tally-mcp-server/ 替换为你实际的项目路径！

Windows 设置

1. 打开：%APPDATA%\Claude\claude_desktop_config.json
2. 使用相同的 JSON 结构，并使用 Windows 路径：

   {
     "mcpServers": {
       "tally": {
         "command": "node",
         "args": ["C:\\path\\to\\your\\tally-mcp-server\\start-server.js"],
         "env": {
           "TALLY_API_KEY": "tally_your_actual_api_key_here"
         }
       }
     }
   }
   

Linux 设置

1. 打开：~/.config/Claude/claude_desktop_config.json
2. 使用相同的 JSON 结构，并使用 Linux 路径。

5. 测试设置

1. 完全重启 Claude Desktop（退出并重新打开）。
2. 开始一个新的对话。
3. 尝试输入："Can you list my Tally forms?"

🤔 可用工具（共 23 种）

表单管理（5 种工具）

• get_tally_forms - 列出所有表单
• create_tally_form - 创建新表单
• get_tally_form - 获取特定表单的详细信息
• update_tally_form - 使用完整的 API 支持和增强的块结构更新表单
• delete_tally_form - 删除表单

提交记录管理（3 种工具）

• get_form_submissions - 分页列出表单提交记录
• get_form_submission - 获取特定提交记录的详细信息
• delete_form_submission - 删除提交记录

问题管理（1 种工具）

• get_form_questions - 列出表单中的所有问题

Webhook 管理（4 种工具）

• get_tally_webhooks - 列出表单的 Webhook
• create_tally_webhook - 创建新的 Webhook
• update_tally_webhook - 更新现有的 Webhook
• delete_tally_webhook - 删除 Webhook

表单构建与模板（2 种工具）

• get_tally_block_types - 获取所有可用表单块类型的完整文档
• get_tally_form_templates - 获取常见用例的预建表单模板

高级条件逻辑（5 种工具）

• create_conditional_logic_block - 创建具有验证功能的结构合理的条件逻辑块
• validate_form_logic_flow - 分析和验证表单的逻辑流程，以识别问题
• get_conditional_logic_templates - 获取常见场景的预建条件逻辑模板
• validate_multiple_choice_logic - 关键 - 防止破坏多项选择条件逻辑的“等于”与“包含”错误
• create_dynamic_question_sets - 关键 - 创建具有根据先前答案更改的条件选项集的问题

表单编辑辅助工具（3 种工具）

• update_form_status - 快速更改表单状态（空白、已发布、草稿）
• update_form_settings - 更新常见的表单设置
• configure_form_notifications - 设置电子邮件通知

💻 使用示例

基础用法

配置完成后，你可以自然地与 Tally 表单进行交互：

• "Show me all my forms"
• "Create a new customer feedback form"
• "What types of form blocks are available in Tally?"
• "Give me a contact form template"
• "Build a survey with rating questions and multiple choice"
• "Create conditional logic that shows different questions based on user type"
• "Validate my multiple choice logic to prevent survey failures"
• "Create a dynamic question like Q5 in BestSelf survey with conditional option sets"
• "Check my conditional logic flow for dead ends"
• "Update my contact form to published status"
• "Get the latest 10 submissions for form xyz"
• "Set up email notifications for my survey"
• "Add a webhook to my form that sends to my API"
• "Delete submissions older than 30 days"
• "Change my form password to 'newpassword123'"
• "Show me templates for lead generation forms"

🔧 高级配置

增强的表单构建功能

该服务器现在提供全面的表单构建支持：

• 块类型参考：完整记录所有 20 多种 Tally 块类型，包括输入字段、布局元素和逻辑块。
• 表单模板：为联系表单、调查问卷、注册表单等提供预建模板。
• 专业结构：遵循最佳实践的即用型表单布局。
• 高级条件逻辑：具备验证和错误预防功能的企业级条件逻辑。
• 关键错误预防：自动检测会破坏调查的逻辑错误。
• 动态问题管理：处理具有条件选项集的复杂问题。

关键条件逻辑特性

• 多项选择验证：防止破坏多项选择条件逻辑的关键“等于”与“包含”错误。
• 动态问题集：创建复杂调查问卷中类似 Q5/Q6 的复杂问题，根据先前答案显示不同选项。
• 逻辑流程分析：全面验证，以捕获无法访问的块、循环逻辑和缺失的引用。
• 企业模式：提供渐进式披露、分支调查、资格流程等模板。

可用的块类型

• 输入块：文本、电子邮件、电话、日期、多项选择、复选框、下拉菜单、评分、排名、文件上传、签名、支付
• 布局块：声明文本、问题组、分隔符、图像、视频、嵌入内容
• 逻辑块：条件跳转、计算器、隐藏字段

自定义表单更新

update_tally_form 工具支持全面的表单编辑，包括：

• 基本属性：名称、状态
• 表单结构：具有详细验证的完整块/问题数组
• 高级设置：20 多种选项，包括通知、样式、行为
• 安全性：密码保护、提交限制
• 集成：重定向、自定义 CSS、数据保留

环境变量

# 必需
TALLY_API_KEY=tally_your_api_key_here

# 可选（用于开发）
NODE_ENV=development
DEBUG=true

替代配置方法

你也可以直接在 Claude Desktop 配置中设置 API 密钥：

{
  "mcpServers": {
    "tally": {
      "command": "node",
      "args": ["/path/to/your/tally-mcp-server/start-server.js"],
      "env": {
        "TALLY_API_KEY": "tally_your_actual_api_key_here"
      }
    }
  }
}

🐛 故障排除

常见问题

1. "Command not found" 错误
   • 验证 Node.js 安装：node --version
   • 检查 Claude 配置中的绝对路径
   • 确保 start-server.js 文件存在且可执行
2. "Authentication failed" 错误
   • 仔细检查 .env 或 Claude 配置中的 API 密钥
   • 确保 API 密钥以 tally_ 开头
   • 验证你的 Tally 账户是否具有 API 访问权限
3. Claude 中未显示工具
   • 完全重启 Claude Desktop（退出并重新打开）
   • 检查配置文件中的 JSON 语法（使用 JSON 验证器）
   • 验证文件路径是否为绝对路径，而不是相对路径
   • 检查 Claude Desktop 日志中的错误信息
4. "Module not found" 错误
   • 在项目目录中运行 npm install
   • 确保 npm run build 成功完成
   • 检查 build/ 目录是否存在

本地测试

# 测试服务器启动是否无错误
npm start

# 或者直接使用启动脚本
node start-server.js

# 使用简单的 API 调用进行测试（需要在 .env 中设置 API 密钥）
curl -H "Authorization: Bearer $TALLY_API_KEY" https://api.tally.so/forms

调试模式

通过设置环境变量启用调试日志：

DEBUG=true NODE_ENV=development node start-server.js

获取帮助

如果你仍然遇到问题：

1. 查看 GitHub 问题。
2. 创建一个新问题，并提供以下信息：
   • 你的操作系统
   • Node.js 版本（node --version）
   • 错误消息
   • 你的配置（不包含 API 密钥）

📚 详细文档

本 MCP 服务器实现了完整的 Tally API，包括：

• 表单 API - 完整的 CRUD 操作
• 提交记录 API - 检索和管理表单响应
• 问题 API - 访问表单结构
• Webhook API - 实时集成

支持的 Tally API 端点

• GET /forms - 列出表单
• POST /forms - 创建表单
• GET /forms/{id} - 获取表单
• PATCH /forms/{id} - 更新表单
• DELETE /forms/{id} - 删除表单
• GET /forms/{id}/submissions - 列出提交记录
• GET /forms/{id}/submissions/{id} - 获取提交记录
• DELETE /forms/{id}/submissions/{id} - 删除提交记录
• GET /forms/{id}/questions - 列出问题
• GET /forms/{id}/webhooks - 列出 Webhook
• POST /forms/{id}/webhooks - 创建 Webhook
• PATCH /forms/{id}/webhooks/{id} - 更新 Webhook
• DELETE /forms/{id}/webhooks/{id} - 删除 Webhook

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

开发设置

# 克隆并安装依赖
git clone https://github.com/cathrynlavery/tally-mcp-server.git
cd tally-mcp-server
npm install

# 设置环境
cp .env.example .env
# 将你的 API 密钥添加到 .env 文件中

# 开发时自动重建
npm run dev

# 为生产环境构建
npm run build

# 运行测试（如果可用）
npm test

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🙏 致谢

• Tally - 出色的表单构建器，使本项目成为可能。
• Claude Desktop - 支持 MCP 协议的 AI 助手。
• Anthropic - 提供模型上下文协议规范。

由 @cathrynlavery 用心打造

免费试用 Tally - 无限表单和提交记录！