# clappia-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/clappia-dev/clappia-mcp  
**GitHub Stars:** 2  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/clappia-mcp

## Description
An MCP server that provides integration with Clappia platform

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "clappia-mcp": {
    "url": "https://www.clappia.com"
  }
}
```

## Documentation & README

# 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](https://www.clappia.com) 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](https://claude.ai/download) or [Windows](https://claude.ai/download)
   -  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

3. **Clone the repository**:

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

4. **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

```
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**

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

2. **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
   )
   ```

3. **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'"
   )
   ```

4. **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"
   )
   ```

5. **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:

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](https://developer.clappia.com/) for:
      -  API reference
      -  Authentication guide
      -  Rate limits
      -  Best practices
      -  Example implementations

4. **API Versioning**:
   -  Current stable version: v1
   -  Backward compatibility maintained
   -  Deprecation notices provided