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 - 無限表單和提交記錄！