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:// .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.

1. 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: json { "mcpServers": { "clappia-mcp": { "command": "uv", "args": [ "--directory", "/Users/ /Desktop/clappia-mcp", "run", "clappia-mcp.py" ], "env": { "CLAPPIA_API_KEY": " ", "CLAPPIA_WORKPLACE_ID": " " } } } }
• Restart Claude for Desktop
• Verify the MCP server is running by checking for the tools icon in the input box

1. Clone the repository:

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

cd clappia-mcp

1. 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

1. API Connection Issues:

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

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

1. 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 )

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

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

1. 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

1. Endpoints:

• Application management
• Form submissions
• Field operations
• User management
• Analytics and reporting

1. API Documentation:

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

1. API Versioning:

• Current stable version: v1
• Backward compatibility maintained
• Deprecation notices provided