limesurvey-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@limesurvey-mcp-server create a new survey from the template file survey.lss"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
limesurvey-mcp
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) acceptfile_path; export methods (export_responses,export_statistics, ...) acceptoutput_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-mcpIt 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-mcpBoth 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-thisOption 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 packageThe 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, andactivate_surveyare destructive or hard to reverse.invite_participants,remind_participants, andmail_registered_participantssend real emails.The
.envfile (if you use one) contains credentials: don't commit it to version control (.gitignorealready 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-serverLicense
MIT. See LICENSE.
Available Tools
27 toolsactivate_surveyADestructive
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_groupBDestructive
Delete a group from a survey. Returns the deleted ID.
Inputs: iGroupID (required), iSurveyID (required).
delete_questionADestructive
Delete a question by its ID. Returns the deleted ID.
Inputs: iQuestionID (required).
delete_surveyADestructive
Delete a survey by its ID. Irreversible.
Inputs: iSurveyID (required).
get_fieldmapBRead-only
Get the fieldmap of a survey.
Inputs: surveyId (required), language.
get_group_propertiesBRead-only
Get properties of a group.
Inputs: iGroupID (required), sLanguage, aGroupSettings.
get_question_propertiesBRead-only
Get properties of a question (includes answeroptions, subquestions, attributes...).
Inputs: iQuestionID (required), sLanguage, aQuestionSettings.
get_summaryARead-only
Participation summary for a survey (complete/incomplete responses, token usage...).
Inputs: iSurveyID (required), sStatName.
get_survey_propertiesARead-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_testARead-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_groupsARead-only
List the question groups of a survey.
Inputs: iSurveyID (required), sLanguage.
list_questionsARead-only
List questions (and subquestions) of a survey or group.
Inputs: iSurveyID (required), iGroupID, sLanguage.
list_quotasARead-only
List the quotas of a survey.
Inputs: iSurveyID (required).
list_surveysARead-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
Scored across 27 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseBqualityDmaintenanceA simple server that enables management of LimeSurvey surveys and responses through MCP client integration.355Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables interaction with LimeSurvey API to create and manage surveys, questions, question groups, activate surveys, and export responses through standardized MCP endpoints.-
- AlicenseCqualityDmaintenanceMCP 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.544MIT
- AlicenseNot gradedqualityCmaintenancePublic MCP server for agent-created, human-friendly, short-lived surveys. Enables agents to ask structured questions and retrieve answers.2MIT