io.github.clappia-dev/clappia-mcp

Official

by clappia-dev · Python

An MCP server that provides Clappia workspace, forms, workflows, submissions, and analytics

Access Clappia workspace data including forms, workflows, submissions, and analytics.

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:

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:

bash

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

Set up Python Environment:

bash

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

# Install dependencies
uv sync

Project Structure

code

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

python

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

python

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

python

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

python

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

python

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

Install

Configuration

Environment variables

CLAPPIA_API_KEYrequiredsecret

Clappia API key for authentication

claude_desktop_config.json

{
  "mcpServers": {
    "clappia-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/okaru413/clappia-mcp:1.0.1"
      ],
      "env": {
        "CLAPPIA_API_KEY": "<YOUR_CLAPPIA_API_KEY>"
      }
    }
  }
}