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

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.

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

Clone the repository:

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

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

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

API Connection Issues:

Verify API credentials in claude_desktop_config.json file
Check network connectivity
Review API rate limits

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

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
                   )
               ]
           )
       ]
   )

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
   )

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'"
   )

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

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:

Check the documentation
Review existing issues
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:

Authentication:

API key-based authentication
Secure credential management
Rate limiting support

Endpoints:

Application management
Form submissions
Field operations
User management
Analytics and reporting

API Documentation:

Visit Clappia Developer Portal for:
API reference
Authentication guide
Rate limits
Best practices
Example implementations

API Versioning:

Current stable version: v1
Backward compatibility maintained
Deprecation notices provided

clappia-mcp