io.github.clappia-dev/clappia-mcp

Clappia MCP (Model Context Protocol)

A Python-based MCP server that provides a comprehensive interface for interacting with the Clappia platform. This server enables programmatic management of Clappia applications, forms, submissions, and more.

Clappia is a no-code platform that allows businesses, operations teams, and non-developers to create custom apps—like inspection forms, approval workflows, field data collection tools, internal dashboards, and more—without writing a single line of code. It's used across industries for automating manual processes, digitizing paperwork, and improving operational efficiency. Click here to learn more.

Features

• App Management
  • Create new Clappia apps with customizable sections and fields
  • Retrieve detailed app definitions with field metadata
• Submission Management
  • Create new submissions with field data
  • Edit existing submissions with validation
  • Update submission status with optional comments
  • Manage submission owners with email-based assignments
  • Retrieve submissions with advanced filtering and pagination
  • Get submission aggregations for analytics with customizable dimensions
• Field Management
  • Add new fields with comprehensive configuration options
  • Update field properties including validation, display conditions, and layout
  • Configure field validations (number, email, URL, custom)
  • Set up conditional logic for field display and editability
  • Manage field layouts with responsive design options

Prerequisites

• Python 3.8 or higher
• uv python package manager
• Access to Clappia API Key and Workplace ID
• Claude for Desktop (or any other MCP Clients)

Installation

1. Set up Clappia API Access:
   • Visit your Workplace in Clappia (https://<your_workplace>.clappia.com), you need to have Workplace Manager Access to this Workplace.
   • Visit Workplace Settings. Note your Workplace ID.
   • Visit Workplace Settings -> Preferences -> API Keys. Note your API Key, generate one if it is not yet generated.
2. Set up Claude for Desktop:
   • Download Claude for Desktop for macOS or Windows
   • Install and launch Claude for Desktop
   • Open Claude menu → Settings → Developer → Edit Config
   • Add the following configuration to claude_desktop_config.json:

      {
         "mcpServers": {
            "clappia-mcp": {
               "command": "uv",
               "args": [
                  "--directory",
                  "/Users/<YOUR_DIECTORY>/Desktop/clappia-mcp",
                  "run",
                  "clappia-mcp.py"
               ],
               "env": {
                  "CLAPPIA_API_KEY": "<ENTER_YOUR_WORKPLACE_API_KEY_HERE>",
                  "CLAPPIA_WORKPLACE_ID": "<ENTER_YOUR_WORKPLACE_ID_HERE>"
               }
            }
         }
      }

   • Restart Claude for Desktop
   • Verify the MCP server is running by checking for the tools icon in the input box
3. Clone the repository:

    git clone https://github.com/clappia-dev/clappia-mcp.git
    cd clappia-mcp

4. Set up Python Environment:

    # Install uv if not already installed
    curl -LsSf https://astral.sh/uv/install.sh | sh
   
    # Install dependencies
    uv sync

Project Structure

clappia-mcp/
├── clappia-mcp.py          # Main MCP server implementation
├── tools/                  # Core functionality modules
│   ├── add_field.py        # Field addition functionality
│   ├── create_app.py       # App creation functionality
│   ├── create_submission.py # Submission creation
│   ├── edit_submission.py  # Submission editing
│   ├── get_definition.py   # App definition retrieval
│   ├── get_submissions.py  # Submission retrieval
│   ├── get_submissions_aggregation.py # Analytics functionality
│   ├── update_field.py     # Field update functionality
│   ├── update_submission_owners.py # Owner management
│   └── update_submission_status.py # Status management
├── pyproject.toml         # Project metadata and dependencies
├── uv.lock               # Dependency lock file (if using uv)
└── .env                  # Environment variables

Usage

• The server will automatically start when Claude Desktop launches
• Access tools through the Claude Desktop interface

Troubleshooting

1. Server Not Starting:
   • Check Claude Desktop logs for errors
   • Verify Python environment is activated
   • Ensure all dependencies are installed
   • Check environment variables are set correctly
2. API Connection Issues:
   • Verify API credentials in claude_desktop_config.json file
   • Check network connectivity
   • Review API rate limits
3. Tool Execution Failures:
   • Check server logs for detailed error messages
   • Verify input parameters match API requirements
   • Ensure proper permissions for API operations

Example API Calls

1. Create a New Application

    from tools.create_app import create_app, Section, Field
   
    result = create_app(
        app_name="Employee Survey",
        requesting_user_email_address="user@company.com",
        sections=[
            Section(
                sectionName="Personal Information",
                fields=[
                    Field(
                        fieldType="singleLineText",
                        label="Full Name",
                        required=True
                    )
                ]
            )
        ]
    )

2. Add a Field to an Application

    from tools.add_field import add_field_to_app
   
    result = add_field_to_app(
        app_id="APP123",
        requesting_user_email_address="user@company.com",
        section_index=0,
        field_index=1,
        field_type="singleLineText",
        label="Employee ID",
        required=True,
        validation="number",
        block_width_percentage_desktop=50,
        block_width_percentage_mobile=100
    )

3. Update a Field

    from tools.update_field import update_field_in_app
   
    result = update_field_in_app(
        app_id="APP123",
        requesting_user_email_address="user@company.com",
        field_name="employeeName",
        label="Full Employee Name",
        required=True,
        validation="none",
        display_condition="status == 'active'"
    )

4. Create a Submission

    from tools.create_submission import create_app_submission
   
    result = create_app_submission(
        app_id="APP123",
        data={"employeeName": "John Doe", "employeeId": "12345"},
        email="user@company.com"
    )

5. Get Submissions with Filtering

    from tools.get_submissions import get_app_submissions, Filters, QueryGroup, Query, Condition
   
    filters = Filters(queries=[
        QueryGroup(queries=[
            Query(
                conditions=[
                    Condition(
                        operator="EQ",
                        filterKeyType="STANDARD",
                        key="status",
                        value="active"
                    )
                ],
                operator="AND"
            )
        ])
    ])
   
    result = get_app_submissions(
        app_id="APP123",
        requesting_user_email_address="user@company.com",
        page_size=10,
        filters=filters
    )

API Documentation

Field Types

• Text Fields
  • singleLineText: Single line text input
  • multiLineText: Multi-line text input
  • richTextEditor: Rich text editor with formatting
• Selector Fields
  • singleSelector: Single choice selection
  • multiSelector: Multiple choice selection
  • dropDown: Dropdown selection
• Date/Time Fields
  • dateSelector: Date selection
  • timeSelector: Time selection
  • dateTime: Combined date and time selection
• File Fields
  • file: File upload with configurable types
  • camera: Direct camera capture
  • signature: Digital signature capture
• Advanced Fields
  • calculationsAndLogic: Formula-based calculations
  • gpsLocation: Location tracking
  • codeScanner: Barcode/QR code scanning
  • nfcReader: NFC tag reading
  • liveTracking: Real-time location tracking
  • address: Address input with validation

Validation Types

• none: No validation
• number: Numeric validation
• email: Email format validation
• url: URL format validation
• custom: Custom validation rules

Field Properties

• Layout
  • block_width_percentage_desktop: Width on desktop (25, 50, 75, 100)
  • block_width_percentage_mobile: Width on mobile (50, 100)
  • number_of_cols: Number of columns for selector fields
• Behavior
  • required: Whether field is mandatory
  • is_editable: Whether field can be edited
  • hidden: Whether field is hidden
  • retain_values: Whether to retain values when hidden
• Conditions
  • display_condition: Condition for field visibility
  • editability_condition: Condition for field editability
• File Settings
  • allowed_file_types: List of allowed file types
  • max_file_allowed: Maximum files allowed (1-10)
  • image_quality: Image quality (low, medium, high)
  • file_name_prefix: Prefix for uploaded files

Error Handling

The server implements comprehensive error handling for:

• Invalid API credentials
• Network connectivity issues
• Invalid input parameters
• API rate limiting
• Server errors

All errors are logged with appropriate context for debugging.

Security

• API keys are stored in environment variables
• All API calls are made over HTTPS
• Input validation is implemented for all parameters
• Rate limiting is supported
• Error messages are sanitized

Performance Considerations

• Connection pooling for API requests
• Efficient payload construction
• Proper resource cleanup
• Logging optimization
• Error handling optimization

Support

For support, please:

1. Check the documentation
2. Review existing issues
3. Create a new issue if needed

License

This project is licensed under the MIT License - see the LICENSE file for details.

API Integration

Clappia Public API

The MCP server integrates with Clappia's public API to provide the following capabilities:

1. Authentication:
   • API key-based authentication
   • Secure credential management
   • Rate limiting support
2. Endpoints:
   • Application management
   • Form submissions
   • Field operations
   • User management
   • Analytics and reporting
3. API Documentation:
   • Visit Clappia Developer Portal for:
     • API reference
     • Authentication guide
     • Rate limits
     • Best practices
     • Example implementations
4. API Versioning:
   • Current stable version: v1
   • Backward compatibility maintained
   • Deprecation notices provided