tally-mcp-server

cathrynlavery/tally-mcp-server

3.2

If you are the rightful owner of tally-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Tally MCP Server is a comprehensive Model Context Protocol server designed for managing Tally forms, submissions, questions, webhooks, and conditional logic through Claude Desktop.

Tools
5
Resources
0
Prompts
0

Tally MCP Server

A comprehensive Model Context Protocol (MCP) server for Tally form management. This server provides 23 powerful tools to manage forms, submissions, questions, webhooks, and enterprise-grade conditional logic directly through Claude Desktop.

Built by @cathrynlavery | Try Claude Desktop | Get Tally Forms

✨ Features

  • 23 comprehensive tools for complete Tally form management
  • Enterprise-grade conditional logic with critical error prevention
  • Advanced form building with block types documentation and templates
  • Form templates for common use cases (contact, survey, registration, etc.)
  • Complete block type reference covering 20+ input, layout, and logic blocks
  • Critical validation tools to prevent survey-breaking logic errors
  • Dynamic question management for complex conditional option sets
  • Full API coverage including advanced form editing capabilities
  • Seamless Claude Desktop integration via MCP protocol
  • Type-safe with proper JSON schema validation
  • Production-ready with error handling and logging

🚀 Quick Start

Prerequisites

  1. Node.js (v16 or higher)
  2. Claude Desktop application
  3. Tally account with API access

1. Installation

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

2. Get Your Tally API Key

  1. Sign up for Tally (free account works!)
  2. Go to https://tally.so/settings/api
  3. Create a new API key
  4. Copy the API key (starts with tally_)

3. Configure Environment Variables

# Copy the example environment file
cp .env.example .env

# Edit .env and add your API key
TALLY_API_KEY=tally_your_actual_api_key_here

4. Configure Claude Desktop

macOS Setup

  1. Open your Claude Desktop configuration file:

    # Create the directory if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude

# Open the config file (create if it doesn't exist)
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

  2. Add the Tally MCP server configuration:

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

    Important: Replace /path/to/your/tally-mcp-server/ with your actual project path!

Windows Setup
  1. Open: %APPDATA%\Claude\claude_desktop_config.json
  2. Use the same JSON structure with Windows paths: 
    {
  "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 Setup
  1. Open: ~/.config/Claude/claude_desktop_config.json
  2. Use the same JSON structure with Linux paths

5. Test the Setup

  1. Restart Claude Desktop completely (quit and reopen)
  2. Start a new conversation
  3. Try: "Can you list my Tally forms?"

🤔 Available Tools (23 Total)

Forms Management (5 tools)

  • get_tally_forms - List all your forms
  • create_tally_form - Create new forms
  • get_tally_form - Get specific form details
  • update_tally_form - Update forms with full API support and enhanced block structure
  • delete_tally_form - Delete forms

Submissions Management (3 tools)

  • get_form_submissions - List form submissions with pagination
  • get_form_submission - Get specific submission details
  • delete_form_submission - Delete submissions

Questions Management (1 tool)

  • get_form_questions - List all questions in a form

Webhooks Management (4 tools)

  • get_tally_webhooks - List webhooks for a form
  • create_tally_webhook - Create new webhooks
  • update_tally_webhook - Update existing webhooks
  • delete_tally_webhook - Delete webhooks

Form Building & Templates (2 tools)

  • get_tally_block_types - Get comprehensive documentation of all available form block types
  • get_tally_form_templates - Get pre-built form templates for common use cases

Advanced Conditional Logic (5 tools)

  • create_conditional_logic_block - Create properly structured conditional logic blocks with validation
  • validate_form_logic_flow - Analyze and validate the logical flow of forms to identify issues
  • get_conditional_logic_templates - Get pre-built conditional logic templates for common scenarios
  • validate_multiple_choice_logic - CRITICAL - Prevent "equals" vs "contains" errors that break multiple choice conditional logic
  • create_dynamic_question_sets - CRITICAL - Create questions with conditional option sets that change based on previous answers

Form Editing Helpers (3 tools)

  • update_form_status - Quick status changes (BLANK, PUBLISHED, DRAFT)
  • update_form_settings - Update common form settings
  • configure_form_notifications - Set up email notifications

💬 Example Usage in Claude

Once configured, you can interact naturally with your Tally forms:

  • "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"

🔧 Advanced Configuration

Enhanced Form Building Capabilities

The server now includes comprehensive form building support:

  • Block Type Reference: Complete documentation of all 20+ Tally block types including input fields, layout elements, and logic blocks
  • Form Templates: Pre-built templates for contact forms, surveys, registration forms, and more
  • Professional Structures: Ready-to-use form layouts following best practices
  • Advanced Conditional Logic: Enterprise-grade conditional logic with validation and error prevention
  • Critical Error Prevention: Automatic detection of logic errors that would break surveys
  • Dynamic Question Management: Handle complex questions with conditional option sets

Critical Conditional Logic Features

  • Multiple Choice Validation: Prevents the critical "equals" vs "contains" error that breaks multiple choice conditional logic
  • Dynamic Question Sets: Create sophisticated questions like Q5/Q6 in complex surveys that show different options based on previous answers
  • Logic Flow Analysis: Comprehensive validation to catch unreachable blocks, circular logic, and missing references
  • Enterprise Patterns: Templates for progressive disclosure, branching surveys, qualification flows, and more

Block Types Available

  • Input Blocks: Text, email, phone, date, multiple choice, checkboxes, dropdown, rating, ranking, file upload, signature, payment
  • Layout Blocks: Statement text, question groups, dividers, images, videos, embeds
  • Logic Blocks: Conditional jumps, calculators, hidden fields

Custom Form Updates

The update_tally_form tool supports comprehensive form editing including:

  • Basic Properties: name, status
  • Form Structure: complete blocks/questions array with detailed validation
  • Advanced Settings: 20+ options including notifications, styling, behavior
  • Security: password protection, submission limits
  • Integrations: redirects, custom CSS, data retention

Environment Variables

# Required
TALLY_API_KEY=tally_your_api_key_here

# Optional (for development)
NODE_ENV=development
DEBUG=true

Alternative Configuration Methods

You can also set the API key directly in the Claude Desktop config:

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

🐛 Troubleshooting

Common Issues

  1. "Command not found" error

    • Verify Node.js installation: node --version
    • Check the absolute path in your Claude config
    • Ensure the start-server.js file exists and is executable

  2. "Authentication failed" error

    • Double-check your API key in .env or Claude config
    • Ensure API key starts with tally_
    • Verify your Tally account has API access

  3. Tools not appearing in Claude

    • Restart Claude Desktop completely (quit and reopen)
    • Check JSON syntax in config file (use a JSON validator)
    • Verify file paths are absolute, not relative
    • Check Claude Desktop logs for errors

  4. "Module not found" errors

    • Run npm install in the project directory
    • Ensure npm run build completed successfully
    • Check that the build/ directory exists

Testing Locally

# Test the server starts without errors
npm start

# Or use the start script directly
node start-server.js

# Test with a simple API call (requires API key in .env)
curl -H "Authorization: Bearer $TALLY_API_KEY" https://api.tally.so/forms

Debug Mode

Enable debug logging by setting environment variables:

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

Getting Help

If you're still having issues:

  1. Check the GitHub Issues
  2. Create a new issue with:
    • Your operating system
    • Node.js version (node --version)
    • Error messages
    • Your configuration (without API keys)

📚 API Reference

This MCP server implements the full Tally API including:

  • Forms API - Complete CRUD operations
  • Submissions API - Retrieve and manage form responses
  • Questions API - Access form structure
  • Webhooks API - Real-time integrations

Supported Tally API Endpoints

  • GET /forms - List forms
  • POST /forms - Create form
  • GET /forms/{id} - Get form
  • PATCH /forms/{id} - Update form
  • DELETE /forms/{id} - Delete form
  • GET /forms/{id}/submissions - List submissions
  • GET /forms/{id}/submissions/{id} - Get submission
  • DELETE /forms/{id}/submissions/{id} - Delete submission
  • GET /forms/{id}/questions - List questions
  • GET /forms/{id}/webhooks - List webhooks
  • POST /forms/{id}/webhooks - Create webhook
  • PATCH /forms/{id}/webhooks/{id} - Update webhook
  • DELETE /forms/{id}/webhooks/{id} - Delete webhook

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

# Clone and install
git clone https://github.com/cathrynlavery/tally-mcp-server.git
cd tally-mcp-server
npm install

# Set up environment
cp .env.example .env
# Add your API key to .env

# Development with auto-rebuild
npm run dev

# Build for production
npm run build

# Run tests (if available)
npm test

📄 License

MIT License - see file for details.

🙏 Acknowledgments

  • Tally - The amazing form builder that makes this possible
  • Claude Desktop - AI assistant with MCP protocol support
  • Anthropic - For the Model Context Protocol specification

Built with ❤️ by @cathrynlavery

Try Tally for free - unlimited forms and submissions!