Clappia MCP

🚀 Clappia MCP (Model Context Protocol)

A Python-based MCP server offering a comprehensive interface to interact with the Clappia platform. It enables programmatic management of Clappia applications, forms, submissions, and more.

Clappia is a no-code platform that empowers businesses, operations teams, and non-developers to create custom apps such as inspection forms, approval workflows, field data collection tools, and internal dashboards without writing any code. It's widely used across industries to automate manual processes, digitize paperwork, and enhance operational efficiency. Click here to learn more.

🚀 Quick Start

This Python-based MCP server provides a comprehensive interface for interacting with the Clappia platform, enabling programmatic management of various aspects of Clappia.

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

📦 Installation

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)

Steps

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

💻 Usage Examples

Basic Usage

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

Advanced Usage

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
)

📚 Documentation

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

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

🔧 Technical Details

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

📄 License

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

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

🆘 Support

For support, please:

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