MCP Server for LimeSurvey

This MCP server enables interaction with the LimeSurvey API while adhering to the Model Context Protocol 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

Clone the repository:

git clone https://gitlab.com/mehdi_guiraud/mcp-limesurvey.git
cd mcp-limesurvey

Configure environment variables:

cp .env.example .env
# Edit .env with your LimeSurvey credentials
nano .env

Install dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Starting the Server

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

Open Claude Desktop
Navigate to Settings → Model Context Protocol
Click Add Custom Server
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

{
  "model": "limesurvey",
  "action": "create_survey",
  "parameters": {
    "survey_title": "Customer Feedback",
    "survey_language": "en"
  }
}

Add a question

{
  "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

{
  "model": "limesurvey",
  "action": "activate_survey",
  "parameters": {
    "survey_id": 123456
  }
}

Export responses

{
  "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:

GET http://localhost:8080/spec

Security

Authentication: Uses credentials stored in .env
Validation: All requests are validated against the MCP schema
Session Management: Automatically caches and recycles LimeSurvey sessions

Customization

To add new API methods:

Add the endpoint in config/config.yaml
Implement the method in app/main.py
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 for details.