shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

tally-mcp-server

Tally MCP Server是一个为Tally表单管理提供全面支持的模型上下文协议服务器，包含23个强大工具，支持表单、提交、问题、Webhook和企业级条件逻辑的管理，可直接通过Claude Desktop操作。

article

README

🚀 Tally MCP 服务器

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

开发者：@cathrynlavery | 试用 Claude Desktop | 获取 Tally 表单

✨ 主要特性

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

🚀 快速开始

前提条件

  1. Node.js（版本 16 或更高）
  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 - 设置电子邮件通知

💬 在 Claude 中的使用示例

配置完成后，你可以自然地与你的 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 密钥）

📚 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 - 无限表单和提交！

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端