Clappia

A Python-based server for programmatically managing Clappia applications, forms, and submissions via its API.

View on GitHub →

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

Related Servers