io.github.clappia-dev/clappia-mcp
An MCP server that provides Clappia workspace, forms, workflows, submissions, and analytics
Open source Open in the app JSON README (API)
About
An MCP server that provides Clappia workspace, forms, workflows, submissions, and analytics
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- clappia-dev
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Stars
- 2
- Last push
- 2026-07-09T11:19:09Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-08-29 03:02:35
- Updated
- 2026-08-29 03:02:35
- Origin id
io.github.clappia-dev/clappia-mcp
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