LimeSurvey MCP Server

A Model Context Protocol (MCP) server that exposes LimeSurvey Remote API functionality as MCP tools. This server provides a standardized way to interact with LimeSurvey's powerful survey management capabilities through MCP clients.

Table of Contents

• Installation
• Configuration
• Usage
• API Reference
  • Survey Management
  • Question Management
  • Response Management
  • Participant Management
  • Statistics Management
• Development
• License

Installation

# Clone the repository
git clone https://github.com/TonisOrmisson/limesurvey-mcp.git
cd limesurvey-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Configuration

Create a .env file in the root directory with the following variables:

# LimeSurvey Remote API Settings
LIMESURVEY_API_URL=https://your-limesurvey-instance.com/admin/remotecontrol
LIMESURVEY_USERNAME=your_username
LIMESURVEY_PASSWORD=your_password

# Server settings
PORT=3000

# Optional: run in read‑only mode
# When true, all write tools short‑circuit and return an error message
# instead of calling LimeSurvey.
READONLY_MODE=false

Usage

Once the server is running, you can use any MCP client to connect to it and access LimeSurvey functionality.

Headless survey construction (addSurvey → groups → questions)

You can build a survey without the LimeSurvey admin UI by combining write tools:

1. addSurvey — create an inactive survey; note the returned survey ID (sid).
2. addGroup — create one or more question groups; each call returns a group ID (gid) for the next step.
3. importQuestion — for each question, pass base64-encoded .lsq content (export a prototype question once from the UI, or generate compatible XML). Use importDataType: lsq.
4. setSurveyProperties — welcome text, description, end URL, etc.
5. activateSurvey — when the structure is ready.

Idempotent rebuilds: use deleteQuestion (per qid, with confirmDeletion: true) and deleteGroup (per survey + gid) to tear down a group or individual questions before re-importing .lsq templates. Deleting a group removes that group’s content; confirm behaviour on your LimeSurvey version in a dev survey first.

Participant link pattern: https://<host>/index.php/<sid> (use sid from addSurvey or listSurveys). Tokenised access uses your existing participant tools.

Example MCP client snippet (pseudo‑YAML) to list surveys:

tool: listSurveys
args: {}

API Reference

RemoteControl2 Coverage

The table below shows how LimeSurvey RemoteControl2 methods are exposed as MCP tools in this server. Methods that are not implemented here are either not available in the target LimeSurvey instance or intentionally skipped (for example unstable or undocumented endpoints).

| Domain | RemoteControl2 method | MCP tool name | Notes | |---------------------|------------------------------|----------------------------|----------------------------------------| | Surveys | list_surveys | listSurveys | read‑only | | Surveys | get_survey_properties | getSurveyProperties | read‑only | | Surveys | activate_survey | activateSurvey | write (guarded by READONLY_MODE) | | Surveys | get_language_properties | getSurveyLanguageProperties | read‑only | | Surveys | get_site_settings | getAvailableLanguages | reads availablelanguages setting | | Surveys | —

... View full README on GitHub