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

1. Clone the repository:

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

2. Configure environment variables:

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

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

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

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

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 for details.