Skip to main content
Glama
limesurvey-mcp-server

limesurvey-mcp-server

by pmanciniq

limesurvey-mcp

Leer en español

MCP (Model Context Protocol) server for LimeSurvey 6's RemoteControl 2 JSON-RPC API. It exposes one MCP tool per API method (import_survey, activate_survey, list_surveys, export_responses, add_participants, etc.), plus a diagnostic tool, limesurvey_connection_test.

This repository is the standalone server: it doesn't depend on any other project. If you're looking for help getting a coding agent to generate .lss/.lsq/.lsg surveys and upload them with this server, check out the limesurvey-ai-boost skill, which is complementary and consumes these same tools.

Features

  • Automatic session handling: credentials come from your configuration; the session key is obtained, cached, and renewed automatically. The MCP client never handles sSessionKey.

  • Files by path: import methods (import_survey, import_group, import_question, upload_file) accept file_path; export methods (export_responses, export_statistics, ...) accept output_path. The server base64-encodes/decodes for you — it never dumps large files into the LLM's context. The same methods also accept base64 content sent directly over HTTP.

  • Actionable errors: API failures come back as ERROR: ... text with the error code (ERR_NO_PERMISSION, ERR_INVALID_SURVEY, ...) instead of a stack trace.

  • Full coverage of the RemoteControl 2 API: surveys, groups, questions, languages, participants/tokens, responses, quotas, users.

Related MCP server: MCP Server for LimeSurvey

Installation

Requires Python ≥3.10. pipx is recommended for installing it in an isolated environment without managing venvs by hand:

pipx install limesurvey-mcp

It also works with plain pip, inside your own virtual environment:

python3 -m venv .venv
source .venv/bin/activate      # on Windows: .venv\Scripts\activate
pip install limesurvey-mcp

Both leave a limesurvey-mcp-server command available (on the PATH with pipx, or inside the venv with pip).

Configuration

The server needs 3 required variables and a few optional ones. You can provide them in two ways:

Option A — direct environment variables (recommended if your MCP client injects them, see below):

LIMESURVEY_URL=https://your-server/index.php/admin/remotecontrol
LIMESURVEY_USERNAME=admin
LIMESURVEY_PASSWORD=change-this

Option B — a .env file. Copy the template and fill it in:

cp .env.example .env    # or download it from the repo if you only installed the package

The server looks for .env in this order: LIMESURVEY_MCP_ENV_FILE (explicit path) → $LIMESURVEY_MCP_HOME/.env → ~/.config/limesurvey-mcp/.env → ./.env in the directory it's launched from. If none is found, it doesn't fail: it assumes the variables are already present in the environment (Option A).

In LimeSurvey: Global settings → Interfaces → RemoteControl must be set to JSON-RPC (this server always uses JSON, never XML-RPC).

Available variables — see .env.example for details on each one (LIMESURVEY_URL, LIMESURVEY_USERNAME, LIMESURVEY_PASSWORD, LIMESURVEY_AUTH_PLUGIN, LIMESURVEY_TIMEOUT, LIMESURVEY_VERIFY_SSL).

Registering the server with your MCP client

stdio transport. Generic example (Claude Desktop, Claude Code, or any other MCP-compatible client):

{
  "mcpServers": {
    "limesurvey": {
      "command": "limesurvey-mcp-server",
      "env": {
        "LIMESURVEY_URL": "https://your-server/index.php/admin/remotecontrol",
        "LIMESURVEY_USERNAME": "admin",
        "LIMESURVEY_PASSWORD": "change-this"
      }
    }
  }
}

If you'd rather not put credentials directly in the client config, omit the env block and use a .env file (Option B) — in that case, add LIMESURVEY_MCP_HOME pointing to the folder where you placed the .env.

Verify the installation with the limesurvey_connection_test tool before operating: it authenticates and returns the site name and how many surveys you can see.

Security

  • The server operates against a real LimeSurvey instance. delete_survey, delete_group, delete_question, delete_response, delete_participants, and activate_survey are destructive or hard to reverse.

  • invite_participants, remind_participants, and mail_registered_participants send real emails.

  • The .env file (if you use one) contains credentials: don't commit it to version control (.gitignore already excludes it) or share it in plain text.

  • Prefer testing against a test instance/survey before pointing at production.

Local development

git clone https://github.com/pmanciniq/limesurvey-mcp-server.git
cd limesurvey-mcp-server
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env   # and fill it in
limesurvey-mcp-server

License

MIT. See LICENSE.

Available Tools

27 tools
activate_surveyA
Destructive

Activate a survey (creates the responses table). Returns the activation result.

Inputs: iSurveyID (required), userActivationSettings.

add_groupA

Add an empty question group. Returns the new group ID.

Inputs: iSurveyID (required), sGroupTitle (required), sGroupDescription.

add_languageC

Add a language to a survey.

Inputs: iSurveyID (required), sLanguage (required).

add_responseB

Add a response to a survey. Returns the ID of the inserted response.

Inputs: iSurveyID (required), aResponseData (required).

add_surveyA

Create an empty survey with the bare minimum (id, title, language). Returns the new survey ID.

Inputs: iSurveyID (required), sSurveyTitle (required), sSurveyLanguage (required), sformat.

copy_surveyA

Copy an existing survey to a new one. Returns the new survey ID.

Inputs: sNewname (required), iSurveyID_org (required), DestSurveyID.

cpd_importParticipantsB

Import participants into the central participants database (CPDB).

Inputs: aParticipants (required), update.

delete_groupB
Destructive

Delete a group from a survey. Returns the deleted ID.

Inputs: iGroupID (required), iSurveyID (required).

delete_questionA
Destructive

Delete a question by its ID. Returns the deleted ID.

Inputs: iQuestionID (required).

delete_surveyA
Destructive

Delete a survey by its ID. Irreversible.

Inputs: iSurveyID (required).

get_fieldmapB
Read-only

Get the fieldmap of a survey.

Inputs: surveyId (required), language.

get_group_propertiesB
Read-only

Get properties of a group.

Inputs: iGroupID (required), sLanguage, aGroupSettings.

get_question_propertiesB
Read-only

Get properties of a question (includes answeroptions, subquestions, attributes...).

Inputs: iQuestionID (required), sLanguage, aQuestionSettings.

get_summaryA
Read-only

Participation summary for a survey (complete/incomplete responses, token usage...).

Inputs: iSurveyID (required), sStatName.

get_survey_propertiesA
Read-only

Get properties of a survey (all or only the ones requested).

Inputs: iSurveyID (required), aSurveySettings.

import_groupA

Import a group (.lsg/.csv file) into a survey. Pass file_path or sImportData in base64.

Inputs: file_path, sImportData, sNewGroupName, sImportDataType, +1 more.

import_surveyA

Import a survey from a .lss/.csv/.txt/.lsa file. Returns the new survey ID. Pass file_path with the local path to the .lss (recommended) OR sImportData in base64.

Inputs: file_path, sImportData, DestSurveyID, sNewSurveyName, +1 more.

limesurvey_connection_testA
Read-only

Verify configuration and connectivity with LimeSurvey: authenticates with the .env credentials and returns the site name and the number of visible surveys. Use it before operating if you're not sure the connection works.

Inputs: no named parameters.

list_groupsA
Read-only

List the question groups of a survey.

Inputs: iSurveyID (required), sLanguage.

list_questionsA
Read-only

List questions (and subquestions) of a survey or group.

Inputs: iSurveyID (required), iGroupID, sLanguage.

list_quotasA
Read-only

List the quotas of a survey.

Inputs: iSurveyID (required).

list_surveysA
Read-only

List the user's surveys (id, title, group, dates, whether active).

Inputs: gsid, sUsername.

mail_registered_participantsB

Send registration emails to the registered participants of a survey.

Inputs: iSurveyID (required), overrideAllConditions.

remind_participantsB

Send email reminders to participants of a survey.

Inputs: iSurveyID (required), aTokenIds, iMaxReminders, continueOnError, +1 more.

set_group_propertiesA

Set properties of a group ('sid' and 'gid' cannot be set).

Inputs: iGroupID (required), aGroupData (required).

set_question_propertiesA

Set properties of a question (qid, gid, sid, type, language... cannot be set).

Inputs: iQuestionID (required), aQuestionData (required), sLanguage.

set_survey_propertiesC

Set properties of a survey.

Inputs: iSurveyID (required), aSurveyData (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 27 tools

    Disambiguation4/5

    Tools are mostly grouped by resource (surveys, groups, questions, participants, responses) and the verb_noun names make their targets clear. A couple of pairs such as get_summary vs get_fieldmap and remind_participants vs mail_registered_participants could be confused, but the descriptions generally resolve the ambiguity.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun snake_case pattern like list_surveys, add_group, and delete_question. The main deviations are cpd_importParticipants, which mixes prefix and camelCase, and limesurvey_connection_test, which is a noun phrase rather than a verb-based action.

    Tool Count2/5

    With 27 tools, the server exceeds the threshold where tool selection becomes unwieldy. While LimeSurvey is a broad domain, many of these tools could be consolidated or the server split into focused sub-servers to reduce mental overhead.

    Completeness2/5

    The server covers surveys, groups, and several property operations, but key lifecycle gaps exist: there is no add_question, no response read/update/delete, no quota mutation, and no survey deactivate/export. These missing operations will cause failures in common LimeSurvey automation workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with LimeSurvey API to create and manage surveys, questions, question groups, activate surveys, and export responses through standardized MCP endpoints.
      -
    • A
      license
      C
      quality
      D
      maintenance
      MCP server that exposes the complete Libredesk REST API (54 endpoints) as tools, enabling natural language management of conversations, contacts, agents, teams, and more for the open-source customer support desk.
      54
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Public MCP server for agent-created, human-friendly, short-lived surveys. Enables agents to ask structured questions and retrieve answers.
      2
      MIT