README.md•3.86 kB
# MCP Server for LimeSurvey
This MCP server enables interaction with the LimeSurvey API while adhering to the [Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18) specifications. It exposes core LimeSurvey functionality through standardized MCP endpoints.
## Features
- 🚀 Survey creation
- ❓ Question and answer management
- 📋 Question group handling
- ✅ Survey activation
- 📊 Response exporting
- 🔍 List available surveys
## Prerequisites
- Python 3.7+
- Access to a LimeSurvey instance (version 3.X+)
- LimeSurvey admin account
## Installation
1. Clone the repository:
```bash
git clone https://gitlab.com/mehdi_guiraud/mcp-limesurvey.git
cd mcp-limesurvey
```
2. Configure environment variables:
```bash
cp .env.example .env
# Edit .env with your LimeSurvey credentials
nano .env
```
3. Install dependencies:
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
## Starting the Server
```bash
./start_server.sh
```
The server will be available at `http://localhost:8080`
## Integration with Claude Desktop
### Step 1: Add the MCP Server in Claude Desktop
1. Open Claude Desktop
2. Navigate to **Settings** → **Model Context Protocol**
3. Click **Add Custom Server**
4. Provide server details:
- **Server Name**: LimeSurvey MCP
- **Base URL**: `http://localhost:8080/mcp`
- **Specification URL**: `http://localhost:8080/spec`
### Step 2: Usage with Claude Desktop
Interact with LimeSurvey directly from Claude Desktop using MCP syntax:
#### Create a new survey
```json
{
"model": "limesurvey",
"action": "create_survey",
"parameters": {
"survey_title": "Customer Feedback",
"survey_language": "en"
}
}
```
#### Add a question
```json
{
"model": "limesurvey",
"action": "add_question",
"parameters": {
"survey_id": 123456,
"group_id": 1,
"question_text": "How satisfied are you with our service?",
"question_type": "5",
"question_options": {
"subquestions": ["Very satisfied", "Satisfied", "Neutral", "Unsatisfied", "Very unsatisfied"]
}
}
}
```
#### Activate a survey
```json
{
"model": "limesurvey",
"action": "activate_survey",
"parameters": {
"survey_id": 123456
}
}
```
#### Export responses
```json
{
"model": "limesurvey",
"action": "export_responses",
"parameters": {
"survey_id": 123456,
"format": "json"
}
}
```
## Available MCP Endpoints
| Action | Required Parameters | Description |
|--------|---------------------|-------------|
| `create_survey` | `survey_title`, `survey_language` | Create a new survey |
| `add_question` | `survey_id`, `group_id`, `question_text`, `question_type` | Add a question to a survey |
| `add_group` | `survey_id`, `group_title`, `group_description` | Add a question group |
| `activate_survey` | `survey_id` | Activate a survey |
| `list_surveys` | None | List all surveys |
| `export_responses` | `survey_id` | Export survey responses |
## Technical Specification
The server fully implements the MCP specification (2025-06-18). Access the complete specification at:
```http
GET http://localhost:8080/spec
```
## Security
1. **Authentication**: Uses credentials stored in `.env`
2. **Validation**: All requests are validated against the MCP schema
3. **Session Management**: Automatically caches and recycles LimeSurvey sessions
## Customization
To add new API methods:
1. Add the endpoint in `config/config.yaml`
2. Implement the method in `app/main.py`
3. Update documentation in the `get_mcp_spec` function
## Troubleshooting
- Ensure RPC API is enabled in LimeSurvey (`Configuration → Interfaces → Enable RPC API`)
- Verify correct credentials in `.env`
- Check server logs for detailed error messages
## License
This project is licensed under MIT. See [LICENSE](LICENSE) for details.