LimeSurvey MCP Server
This server wraps the LimeSurvey RemoteControl 2 API, providing tools for managing surveys, participants, responses, quotas, themes, and more. It includes all 56 official API methods plus 15 additional workflow tools, with robust safety features.
Session Management: Connect and disconnect via
get_session_keyandrelease_session_key.Survey Management: Create, delete, import, copy, activate, list, find, and set properties for surveys; manage survey languages.
Question Groups & Questions: Add, delete, import, list, and modify groups and questions; get field maps.
Participants: Activate token tables; add, delete, list, update, and filter participants; send invitation/reminder emails.
Responses: Add, update, delete responses; export in various formats (inline or to file); export by token; retrieve uploaded files.
Quotas: Add, delete, list, get, and set quota properties.
Statistics & Timeline: Export survey statistics and response timelines.
File Operations: Securely import surveys, groups, and questions from files; export data to dedicated directories with size limits and digests.
Themes: Generate, validate, and assign responsive, WCAG-compliant survey themes.
Capability Detection: Get instance info, list installed themes, discover export formats, and optionally probe live connectivity.
Users: List administration users.
Safety: Read-only mode; explicit confirmations for destructive actions (delete, activation, emails, theme assignment, file overwrite); secure credential handling; sanitized errors.
Additional: Supports stdio and authenticated HTTP transports; Docker deployment; session caching with retry; and experimental features like survey structure export.
Provides tools for interacting with the LimeSurvey RemoteControl 2 API, enabling management of surveys, participants, responses, quotas, themes, and exports in a LimeSurvey instance.
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 list all surveys"
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 Server
A production-oriented Model Context Protocol server for the LimeSurvey RemoteControl 2 API. It exposes all 56 documented RemoteControl methods plus guarded workflow tools for discovery, participants, exports, capability detection, building surveys from a JSON description, and responsive survey themes.
This community project is not affiliated with or endorsed by LimeSurvey GmbH.
Features
Complete RemoteControl coverage: all 56 documented JSON-RPC methods
82 MCP tools: official methods plus focused workflow, survey description, and theme tools
Surveys from a description: validate a JSON survey description, create the survey from it, and read any survey, group, or question back as such a description, without any local file
Modern MCP contracts: strict Zod schemas, structured output, and annotations
Safe write access: server-enforced write scopes (
none,content,lifecycle, outreach), a legacy read-only switch, and explicit confirmationsSession management: cached credentials, one retry after an invalid session, graceful release, timeouts, and sanitized errors
Two transports: stdio for local clients and authenticated Streamable HTTP
Secure exports: bounded base64 decoding into a dedicated directory
Survey theme workflow: generate, validate, publish, and assign responsive themes
Deployment ready: Docker, Compose, healthcheck, CI, and Dependabot
Related MCP server: MCP Server for LimeSurvey
Tool Catalog
Area | Tools | Count |
Official RemoteControl 2 API | Sessions, settings, surveys, languages, groups, questions, participants, quotas, users, responses, files, exports | 56 |
Workflow helpers | Survey search, language normalization, participant helpers, export format discovery, secure file exports, experimental survey-structure export, capability/instance info, participant table status, participant validation, survey-vs-.lss verification, question replacement | 14 |
Survey descriptions (spec) | Validate a description, read a survey, group, or question as a description, create a survey, insert a question or a group at a given position, change a question, change texts per language | 7 |
Survey themes | Generate, validate, publication guide, assign to survey, best-effort theme listing | 5 |
Total | 82 |
Official tools are named limesurvey_<remotecontrol_method>. Run the MCP
Inspector to view every current schema:
npm run inspectQuick Start
Prerequisites
Node.js 20 or newer, or Docker
A reachable LimeSurvey instance
A dedicated LimeSurvey service account with only the required permissions
In LimeSurvey: enable the API and select JSON-RPC under Configuration > Global settings > Interfaces
Option A: npm
npx -y limesurvey-mcp-server@latestThe server uses stdio by default. Supply credentials through the MCP client
configuration shown below. @latest receives the newest release whenever the
MCP process starts; pin an exact version (for example
limesurvey-mcp-server@1.4.0) for reproducible deployments.
npxprefers an existing global installation over a registry download, even a broken or outdated one, so@latestdoes not update a machine that also has the package installed globally. If the server fails to start, see Troubleshooting.
Option B: from source
git clone https://github.com/Wagner-Emden-IT-Services/limesurvey-mcp-server.git
cd limesurvey-mcp-server
npm ci
npm testOption C: Docker
git clone https://github.com/Wagner-Emden-IT-Services/limesurvey-mcp-server.git
cd limesurvey-mcp-server
cp .env.example .env
# Edit .env and use a long random MCP_HTTP_BEARER_TOKEN.
docker compose up --build -dCompose binds 127.0.0.1:3000, starts in read-only mode, and stores exports and
theme packages in separate named volumes.
See Installation and Updates for Codex CLI, Claude Desktop, global npm, source, Docker, verification, update, and removal steps.
Configuration
Required:
Variable | Description |
| Exact RemoteControl URL, for example |
| LimeSurvey service account |
| Service account password, or the path to a file that holds only the password (UTF-8 without BOM). If both are set, the file wins and |
Important optional variables:
Variable | Default | Description |
|
| LimeSurvey authentication plugin |
| unset (= |
|
|
|
|
|
| RemoteControl request timeout |
|
| Maximum inline result size |
| unset | Dedicated output directory for decoded exports |
|
| Maximum decoded export size |
| unset (falls back to | Dedicated input directory for |
|
| Maximum file size accepted via |
| unset | Dedicated output directory for generated theme ZIPs |
|
| Maximum logo and theme entry size |
|
| Enable non-standard |
|
|
|
|
| Streamable HTTP bind address |
|
| Streamable HTTP port |
|
| Streamable HTTP endpoint |
| unset | Required for every non-loopback HTTP binding |
| unset | Comma-separated exact Host allowlist |
| unset | Comma-separated exact browser Origin allowlist |
The server intentionally does not load .env itself. The MCP client, process
manager, or container runtime owns secret injection.
Keeping the password out of the client configuration
With LIMESURVEY_PASSWORD_FILE the password lives in a file that only your own
account can read, instead of in the MCP client configuration (which is often a
readable JSON file or a shell command that ends up in the history). The server
reads the file once at start-up, removes a UTF-8 BOM and the trailing line
ending, and rejects an empty file, invalid UTF-8, and UTF-16 (what Windows
PowerShell 5.1 writes with > or Out-File). It never prints the password or
any part of it: error messages name only the variable and the path, and
limesurvey_get_instance_info reports just password_source (file or
env). On POSIX systems a start-up warning appears when the file is readable
by group or others (chmod 600); on Windows restrict the file with icacls.
Step-by-step commands that never put the password into a command line:
Store the password in a file.
After switching, remove LIMESURVEY_PASSWORD from the client configuration.
MCP Client Setup
Codex CLI:
codex mcp add limesurvey `
--env "LIMESURVEY_URL=https://survey.example.com/index.php/admin/remotecontrol" `
--env "LIMESURVEY_USERNAME=rpc-user" `
--env "LIMESURVEY_PASSWORD=replace-me" `
--env "LIMESURVEY_WRITE_SCOPE=content" `
-- npx -y limesurvey-mcp-server@latestcontent lets an assistant build and correct surveys; use none for read-only
access (see Write Safety).
Example for clients that support mcpServers configuration:
{
"mcpServers": {
"limesurvey": {
"command": "npx",
"args": ["-y", "limesurvey-mcp-server@latest"],
"env": {
"LIMESURVEY_URL": "https://survey.example.com/index.php/admin/remotecontrol",
"LIMESURVEY_USERNAME": "rpc-user",
"LIMESURVEY_PASSWORD": "replace-me",
"LIMESURVEY_WRITE_SCOPE": "content",
"LIMESURVEY_THEME_DIR": "C:/limesurvey-mcp/themes"
}
}
}
}For a local build, replace npx with node and use the absolute path to
dist/src/index.js as the first argument.
Restart the MCP client after changing its configuration. Then call
limesurvey_get_session_key and limesurvey_list_surveys to verify
authentication and read access before enabling writes.
Streamable HTTP
MCP_TRANSPORT=http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=3000 \
MCP_HTTP_BEARER_TOKEN='replace-with-a-long-random-token' \
npm startMCP endpoint:
http://127.0.0.1:3000/mcpHealth endpoint:
http://127.0.0.1:3000/health
Non-loopback bindings fail fast without a bearer token. Use a reverse proxy for TLS and configure Host and Origin allowlists when exposing the server remotely.
Write Safety
LIMESURVEY_WRITE_SCOPE limits what the server may change. The scopes are
cumulative, from narrowest to widest: none < content < lifecycle <
outreach. A tool runs only when the configured scope is at least the tool's
minimum scope. The check is enforced by the server before any file is read or
any RemoteControl request is sent, and it cannot be bypassed through MCP tool
arguments. A blocked call fails with the error code WRITE_SCOPE_INSUFFICIENT
and names the current scope, the required scope, and which variable set it.
Raise the scope deliberately and restart the MCP client completely; do not work
around a block by calling the RemoteControl API directly.
Unset: everything is allowed (effective scope
outreach, the historical default).LIMESURVEY_READ_ONLY=true(or the legacyREADONLY_MODE=true) equalsnone.If both variables are set, the stricter level wins and the server prints a startup warning naming both variables and the effective scope.
For building and correcting surveys,
contentis usually the right level.
Write scope | Tools |
|
|
|
|
|
|
|
|
All 82 tools are listed (43 + 20 + 7 + 12). A tool that is missing from the
server's scope table is treated as outreach. Some calls are argument-dependent:
limesurvey_import_survey with import_data_type=lsa requires outreach,
because a .lsa archive activates the survey and imports participants and
responses; lss, csv, and txt imports stay at content. And
limesurvey_invite_participants with dry_run=true needs only none, because
it sends nothing and never calls invite_participants (see
Checking an invitation run first). The same
holds for limesurvey_update_question_from_spec and
limesurvey_update_survey_texts with dry_run=true: they read only.
content covers every survey setting that LimeSurvey lets
set_survey_properties change, including start and expiry dates, notification
and administrator addresses, and public registration. Choose none when an
assistant should only read.
Additional confirmation literals are required for high-impact actions:
Action | Required argument |
All |
|
Participant email tools |
|
Survey activation |
|
Replacing an export or theme ZIP |
|
Assigning a survey theme |
|
These MCP-only confirmation fields are never forwarded to LimeSurvey.
Error Hints and Write Limits
LimeSurvey's set_*_properties methods silently drop every key they cannot
write, and error_code does not exist in LimeSurvey 6.17.11. The server
therefore checks and explains instead of passing the silence through (all
lists were verified against the LimeSurvey 6.17.11 source; older releases may
differ):
Known non-writable keys are rejected before any request is sent by
set_question_properties,set_group_properties,set_survey_properties,set_language_properties,set_quota_properties, andset_participant_properties. The error hascode: "FIELD_NOT_WRITABLE"and, on the top level next tomessage,hint_code: "NOT_WRITABLE_VIA_REMOTECONTROL", ahintwith the way around it (for example: question attributes, answer options, and subquestions can only be changed by re-importing the question or in the admin UI), andwritable_fields. Unknown keys that are not on the list are not blocked, because releases may add columns; keys the answer does not contain are returned afterwards inwarnings(ignored_fields, orfailed_fieldsfor fields LimeSurvey reported as not saved).Localized texts are routed safely.
question,help, andscript(questions) andgroup_nameanddescription(groups) are moved intoquestionl10ns[<language>]/questiongroupl10ns[<language>], usingdata.language(questions also thelanguageparameter). Without a language the call fails withLANGUAGE_REQUIRED. This avoids LimeSurvey's legacy form, which resets the text field you did not send to an empty string."No data" answers are interpreted.
No valid Data,No available data, andERR_NO_DATAcarryhint_codeNOT_WRITABLE_VIA_REMOTECONTROL(writes),NO_PARTICIPANT_TABLE/NO_RESPONSE_TABLE(get_summary), orNO_DATA(everything else) plus a method-specifichint.More error shapes are detected. An object in
status(set_participant_propertiesvalidation errors) and{success: false, message}(set_quota_properties) now raise errors;error_codeis still honored for newer LimeSurvey versions.
Each set_*_properties tool description lists its writable and non-writable
fields.
Argument errors are explicit: an unknown argument fails with
Unknown argument: <names>. This tool accepts: <parameters>. for every tool.
limesurvey_get_group_properties and limesurvey_get_question_properties
accept an optional MCP-only survey_id (never sent to LimeSurvey, whose
methods take no survey ID): the result's sid must match, otherwise the call
fails with GROUP_SURVEY_MISMATCH or QUESTION_SURVEY_MISMATCH instead of
silently returning another survey's object.
limesurvey_get_language_properties returns the attachments field exactly as
LimeSurvey stores it (keep it unchanged for a round trip to
set_language_properties) and, when attachments is part of the answer, adds
attachments_parsed: { <mail type>: [ { file_name, url, size, relevance } ] }.
LimeSurvey stores a JSON string since DB version 647; older instances hold a PHP
serialize string; both are parsed. An empty value gives {}, an unparsable one
null plus the warning ATTACHMENTS_UNPARSEABLE. Requested property names that
are not a column are dropped silently by LimeSurvey; the server lists them in the
warning UNKNOWN_FIELDS (unknown_fields).
limesurvey_get_participant_table_status answers "does this survey have a
participant table, and is access closed?" without guessing: exists and
participant_count come from get_summary(token_count), and
survey_is_closed_access follows the survey property access_mode (C) where
the release has it, otherwise the participant table
(closed_access_basis names which). The survey property usetokens is not
evaluated by LimeSurvey 6.17.11 and says nothing about either. A get_summary
answer "No available data" is reported as NO_PARTICIPANT_TABLE (no participant
table; access follows access_mode) or NO_RESPONSE_TABLE (survey not active:
never activated or deactivated).
An empty list is not an error: when list_surveys, list_survey_groups,
list_users, list_groups, list_questions, list_quotas, or
list_participants find nothing, LimeSurvey answers with a status text such as
No surveys found; the server returns [] for exactly these methods and
texts. Other statuses, such as Error: No survey participant list (no
participant table), stay errors.
Checking an invitation run first
limesurvey_invite_participants with dry_run=true sends nothing and never
calls invite_participants. It reads the participants (list_participants) and
simulates the selection of LimeSurvey 6.17.11, so you see before the real run who
would be mailed and why the others would not. send_email=false is not a
preview: in LimeSurvey it means "resend the invitation only to participants who
were already invited" and mails them. confirm_send_email is not needed for a
dry run, and a dry run is allowed under every write scope.
The report contains:
would_receive(tid,email,firstname,lastname) in sending order;would_not_receive(tid,email,reasons, optionaldetails) with the reasonscompleted,missing_token,missing_email,already_invited(send_email=true, participant was invited) ornot_invited_yet(send_email=false),emailstatus_not_ok(the value is indetails),invalid_email_address,not_valid_yet(validfromis after the server time),expired(validuntilis before it),not_selected(token_idsset,tidnot in it; these participants are only counted, never listed one by one), andbeyond_maxemails(only whenmaxemailscould be read);without
continue_on_error:stops_at_tid, the first participant whose validity window fails (LimeSurvey stops sending there), andnot_reached;warnings(blanks at the edges, duplicate addresses among the recipients),limitations,time_basis, andborderline(validity limits within 60 minutes of the server time);countswith the full numbers (would_receive,would_not_receive,not_reached,not_selected,by_reason).
The report stays within LIMESURVEY_MAX_RESPONSE_CHARS whatever the table size:
would_receive, would_not_receive and not_reached list at most 100 entries
each, warnings and borderline at most 25. When a list is cut,
truncated_lists names it with returned and total; counts always holds
the complete numbers. Use token_ids to check specific participants.
Known limits, also listed in limitations: the block list of the central
participant database cannot be read through RemoteControl; maxemails (default
50 emails per call) is readable only by super administrators; the address check
is a port of LimeSurvey's own pattern and an approximation of PHP's result; mail
transport errors cannot be simulated. RemoteControl has no clock method, so the
server time is the HTTP Date header of the last answer. validfrom and
validuntil are stored without a zone in the local time of the LimeSurvey
server: pass server_utc_offset_minutes (for example 120 for UTC+2), otherwise
the timezone of the machine running the MCP server is assumed (time_basis
reports the source).
limesurvey_validate_participants checks the whole participant table with the
same code before you invite: whitespace at the edges (WHITESPACE), duplicate
addresses (DUPLICATE_EMAIL, trimmed and case-insensitive) and tokens
(DUPLICATE_TOKEN), address format (INVALID_EMAIL), NOT_YET_VALID,
EXPIRED, INVALID_VALIDITY_RANGE, EMAILSTATUS_NOT_OK, MISSING_EMAIL, and
MISSING_TOKEN. It returns issues (tid, field, code, detail) and
counts_by_code. The answer is bound to LIMESURVEY_MAX_RESPONSE_CHARS: when
there are too many issues, issues and borderline are cut to fit and marked
with issues_truncated, issues_total, issues_returned and a
truncation_note; counts_by_code, participant_count and time_basis are
always complete.
Building Surveys from a Description
The spec tools build and check surveys from a JSON description (the spec), so no
.lss file has to be written or uploaded. The description goes in as a tool
argument and comes back as a tool result; none of these tools needs a local file
path, which keeps them usable from remote MCP clients.
Tool | Write scope | Purpose |
|
| Checks a survey, group, or question description and reports every problem at once with |
|
| Reads a survey, one group ( |
|
| Validates the description before any request, generates the |
|
| Inserts one question into a group of an inactive survey at |
|
| Inserts one group with its questions into an inactive survey at |
|
| Changes one question to the given end state: a dry run shows changes, mode, and risks; the real run writes texts, columns, or replaces the question at the same place, then compares. |
|
| Changes texts of the survey, groups, questions, and subquestions per language, also on active surveys, and reads them back. |
Spec format
{
"survey": {
"title": "Seminar feedback",
"language": "en",
"additional_languages": ["de"],
"description": "", "welcometext": "", "endtext": "",
"anonymized": true, "datestamp": false, "ipaddr": false, "savetimings": false,
"format": "G", "adminemail": "", "showprogress": true,
"expires": "2026-12-31", "template": "vanilla", "showqnumcode": "X"
},
"groups": [
{
"title": "Content",
"description": "",
"relevance": "1",
"questions": [
{
"code": "A01", "type": "F", "text": "How do you rate the following aspects?",
"help": "", "mandatory": false, "relevance": "1", "other": false,
"attributes": {},
"subquestions": [{ "code": "SQ001", "text": "Clarity of the goals" }],
"answers": [
{ "code": "1", "text": "poor", "assessment_value": 1 },
{ "code": "2", "text": "good", "assessment_value": 2 }
]
}
]
}
]
}Question types: all 29 core types,
X L ! O M Y N S T Q 5 F A R K B C E H P D G U I * | 1 : ;.M Q A K B C E Pneed subquestions and no answers;L ! O Rneed answers and no subquestions;F Hneed both;1 : ;see the next point; all others need neither.otheris allowed forL ! M Ponly.Arrays with two scales:
scale_id(0 or 1) marks the second scale. Type1(array dual scale) takes subquestions on scale 0 and answers on scale 0 and 1; types:(array numbers) and;(array texts) take subquestions on scale 0 (rows) and 1 (columns) and no answers. Codes must be unique per scale, so the same code may appear on both scales.get_survey_specwritesscale_idonly for scale 1 and sorts entries by scale.Codes: question codes
^[A-Za-z][A-Za-z0-9]*$(at most 20 characters, unique in the survey without regard to case, not a reserved word such asSID); subquestion codes alphanumeric (at most 20, nottime); answer codes alphanumeric with at most 5 characters (LimeSurvey drops longer codes without a message). Ranking (R) items are answers on LimeSurvey 6 and subquestions on LimeSurvey 7; on 7 an item may have a code of up to 20 characters and its ownrelevance, on 6 such an item is rejected before anything is written. The tools tell the version with one read call (get_group_propertiesfor the group 0).Texts: every text field (survey title, description, welcome and end text, group title and description, question text, help and script, subquestion and answer texts) is a string, which applies to every survey language, or a map per language such as
{"de": "Frage", "en": "Question"}. A map must cover exactly the survey languages; a missing translation is an error with its path, never a silent copy. Default values (default,default_other, subquestiondefault) may cover only some languages. Survey and group titles must not be empty; an empty question, subquestion, or answer text is only a warning.Language-dependent attributes (
prefix,suffix,em_validation_q_tip,other_replace_text,dualscale_headerAand the other ten of LimeSurvey's list) take a string or a map and are written once per language, as are attributes that LimeSurvey stores per language for plugins or custom question themes; the attributes of the core themes that do not depend on the language take one value.Optional fields for round trips of surveys built in the admin UI:
preg,question_theme_name(extended themes such asbootstrap_buttons),encrypted,same_default,same_script,modulename,script,default,default_other, subquestionrelevanceanddefault, grouprandomization_group; the survey's yes/no settings andformatalso take"inherit"/"I".defaultis allowed on question types without subquestions exceptRand|, subquestiondefaulton types with subquestions except1,:and;, anddefault_otheronLand!withother; elsewhere LimeSurvey stores a default but never uses it.mandatoryistrue,false, or"soft".expiresisYYYY-MM-DD HH:MM:SSorYYYY-MM-DD(end of day).Texts may use HTML entities; references that end with
;and do not stand for& < > " 'are decoded (äbecomesä), all others stay as written.Unknown keys, control characters that XML 1.0 forbids, and embedded
data:URIs (which LimeSurvey removes on save) are rejected with their path.The format is backward compatible with the JSON spec of the
limesurveyClaude Code plugin's former Python generator; for every valid spec without language-dependent attributes the generated.lssis byte-identical (seetest/fixtures/lss-parity). Language-dependent attributes are written once per language, because LimeSurvey ignores the rows without a language that the Python generator wrote.
Reading a survey back
limesurvey_get_survey_spec returns the description of a survey, a group, or a
question; its spec can be passed unchanged to limesurvey_create_survey_from_spec
(a survey) and to the group and question tools. Texts always come as maps per
language. Attribute values equal to the theme default are left out, default
values come from get_fieldmap, and Ranking items come back as answers on
LimeSurvey 6 and 7 alike. Texts keep their leading and trailing spaces, script
and preg come back with LF line endings (as LimeSurvey stores them after an
import), and the theme core of old imports counts as the base theme.
unreadable lists what RemoteControl cannot read and a later replacement would
therefore lose: legacy conditions (their logic stays in the stored relevance),
quota members, URL parameter assignments, stored attributes that the question
type or theme does not define, archived responses, and on survey level the
settings outside the spec (navigation, participant and assessment settings,
email templates, URL, privacy texts, date and number format); plus the "other"
default of multiple choice questions. Entries tied to an element carry path
and language. missing_translations lists every text field without a row in a
survey language. When the result would exceed
LIMESURVEY_MAX_RESPONSE_CHARS, the tool answers SPEC_TOO_LARGE with an
outline (group_id, title, number of questions, estimated size) to read group
by group.
Adding a question or a group
limesurvey_add_question_from_spec and limesurvey_add_group_from_spec take the
description of one question or one group, in the same format as inside a survey
spec (a spec from limesurvey_get_survey_spec works unchanged). They check it
against the live survey first: texts in exactly the survey languages, codes that
are free in the survey without regard to case (CODE_CONFLICT otherwise, because
LimeSurvey would rename them silently), an inactive survey (SURVEY_ACTIVE),
the group of the survey (GROUP_SURVEY_MISMATCH), and a valid position
(POSITION_INVALID); none of these errors writes anything. LimeSurvey imports a
question or group at the end; the tools then write order values only for the new
element. LimeSurvey renumbers the order values of the group's questions (or of
the survey's groups) after that, but their sequence stays the same. If a step
after the import fails, the new element is deleted again by the id from the import
answer, and the error reports failed_step, rolled_back, manual_cleanup, and
cause_code. When the outcome of the import itself is unclear (a transport error,
an error after LimeSurvey created the question, an unknown answer), nothing is
deleted: the error reports created: "unknown", the read-only candidates, and a
cleanup_hint.
Importing a question makes LimeSurvey fill missing translations of other
questions in the survey with the base-language text. If the survey has such gaps,
limesurvey_add_question_from_spec refuses with TRANSLATION_GAPS (listing them)
unless acknowledge: ["fill_translation_gaps"] is given; the filled texts are
then listed under side_effects. Importing a group fills nothing.
Changing a question
limesurvey_update_question_from_spec takes the desired end state of one
question, typically the spec of limesurvey_get_survey_spec with the change
applied. Run it first with dry_run: true (write scope none, read methods
only): the result lists changes (path, kind, current, desired), the
mode, the risks (code, blocking, acknowledgeable, detail), the plan,
and the fingerprint of the current question. The real run needs
expected_fingerprint (from the dry run or the read; otherwise STALE_SPEC, nothing
written), confirm_destructive_action: true, and acknowledge for every blocking,
acknowledgeable risk (qid_bound_links, quota_members, other_default,
removals, fill_translation_gaps, answer_code_references; otherwise
UPDATE_QUESTION_BLOCKED, nothing written).
Mode | When | How |
| The end state equals the question | Nothing is written. |
| Only question, help, or subquestion texts change |
|
| Only |
|
| Anything else: answers (including their texts), subquestions, attributes, default values, type, script (inactive survey) | A new question is imported from a generated |
Unchanged texts are written back as LimeSurvey stored them. On an active survey
every change other than texts answers SURVEY_ACTIVE without writing; answer
texts cannot be written on active surveys at all. References from other
questions to the code (code_references), SGQA references, and embedded data URIs
block a run that would break them and cannot be acknowledged; the check reads
relevance, attributes, scripts, default values, and answer texts of every question
(in free texts only expressions in {...}) and also finds removed comment,
other, and array column variables. Texts the question has no row for in a
language count as unchanged; a replacement reports them as unreadable_texts
(acknowledged with fill_translation_gaps). Attributes the new type or theme does
not define, and a question_theme_name of another question type, are errors
before anything is written. Long lists of locations are capped (locations_total).
If only the read-back after a successful write fails, the error is
VERIFY_READ_FAILED with written: true: the change is stored, read the question
again before retrying.
Changing texts
limesurvey_update_survey_texts changes texts of the survey (title,
description, welcometext, endtext), of groups (by group_id), of questions
(text, help, by code), and of subquestions (by code and scale_id), per
language, also on active surveys. Every text is a string for all survey
languages or a map with some of them. Answers and attributes in texts answer
TEXT_NOT_WRITABLE (on an inactive survey use
limesurvey_update_question_from_spec); a group of another survey, an unknown
code, a language the survey does not have, and an embedded data URI in the
affected row are refused before anything is written. dry_run: true lists the
changes under write scope none; expected_fingerprint guards against changes in
between. If a write step fails, the texts already written are set back
(TEXT_UPDATE_FAILED with rolled_back).
Verification
After the import the survey is read back with read methods only and compared
with the description. Question attributes are compared without values that equal
LimeSurvey's default for the question theme (the defaults are generated from the
theme definitions of LimeSurvey 6.17.11 and 7.5.1 by
tools/build-attribute-defaults.mjs). Differences are reported, not hidden; the
created survey stays in place (deleting needs the lifecycle scope).
Responsive Survey Themes
The theme generator was last verified on 2026-10-14 against LimeSurvey CE 7.5.1 (import with Upload & install, installed name, assignment with read-back, rendering). Earlier checks: 2026-07-22 against the then current LimeSurvey CE 7.0.5 release, and 2026-07-24 against the official vanilla 3.0.1 ("Bootstrap Vanilla") manifest. LimeSurvey 7 is the default target; LimeSurvey 6 can be selected explicitly.
Generated themes:
inherit the installed
vanillacore theme instead of copying it —vanillais the minimal official base theme shipped and installed with every LimeSurvey instance, so generated themes no longer depend onfruity_twentythreebeing present;contain responsive CSS, fixed mobile breakpoints, print styles, visible focus, reduced-motion support, and minimum 44 px controls;
validate WCAG contrast for body, muted, focus, and primary-button colors;
use local system font stacks with no third-party font requests;
contain no JavaScript, tracking, remote CSS imports, or data URLs;
optionally include a signature-checked PNG or JPEG logo;
are licensed GPL-2.0-or-later, matching the inherited LimeSurvey theme.
LimeSurvey installs an uploaded theme under the ZIP file name without .zip and
without dots, not under theme_name: weit_feedback-1.0.0-ls7.zip becomes
weit_feedback-100-ls7 (at most 45 characters). The generator, the validator,
and the publication guide return this as installed_theme_name, and
limesurvey_assign_survey_theme takes it. Versions with the same digits
(1.10.0, 11.0.0) give the same installed name; the generator warns about
them. The validator follows the LimeSurvey 7.5.1 import: errors are limited to
archive safety and what LimeSurvey would refuse, skip, or not use, while
warnings starting with policy: mark what LimeSurvey accepts but the generator
never produces (for example JavaScript, another parent theme, a missing
LICENSE.txt, or external URLs in CSS).
Recommended tool sequence:
limesurvey_generate_survey_themelimesurvey_validate_survey_theme; continue only withvalid=trueafter reviewing everypolicy:warning (JavaScript,@import, and external or data URLs in CSS are served to every participant)limesurvey_get_theme_publication_guideusing the installed version shown in LimeSurveyImport the unrenamed ZIP with Upload & install in the theme list under Configuration > Advanced > Themes > Survey themes
Test an inactive survey on phone, tablet, desktop, keyboard, zoom, RTL, and print
limesurvey_assign_survey_themewithinstalled_theme_nameandconfirm_theme_assignment=true; it reads the current theme first (previous_theme), reads the template back, and fails withTHEME_NOT_APPLIEDwhen LimeSurvey kept another theme (THEME_NOT_VERIFIEDwhen only the read-back fails,THEME_PREVIOUS_UNKNOWNwithout writing when the current theme cannot be read)
See Survey Theme Guide for complete examples, acceptance criteria, Cloud restrictions, community publication, and rollback.
Secure File Exports
File export tools require LIMESURVEY_EXPORT_DIR. File names cannot contain
directories, traversal segments, or null bytes. The server enforces decoded size
limits, creates restrictive files, refuses replacement by default, and returns
the path, size, MIME type, and SHA-256 digest instead of base64 content.
The original RemoteControl export methods remain available for compatibility. Oversized inline responses are replaced by a marked preview that is not a valid export file.
Secure File Imports
limesurvey_import_survey, limesurvey_import_group, and
limesurvey_import_question accept an import_data_path argument as an
alternative to inline import_data. Set exactly one of the two; the server
reads the file at import_data_path from LIMESURVEY_IMPORT_DIR (falling
back to LIMESURVEY_EXPORT_DIR when unset) and base64-encodes it itself, so a
survey file of any size can be imported with a single tool call instead of an
inline base64 payload. Use import_data_path for files at or above roughly
50 KB; reserve inline import_data for small files under 200,000 characters
of base64 text.
The path is resolved and checked the same way as export file names: it must
stay inside the configured import directory. Oversized files, missing files,
paths outside the directory, and conflicting/missing parameters all fail with
a distinct error code (IMPORT_FILE_TOO_LARGE, IMPORT_FILE_NOT_FOUND,
IMPORT_PATH_OUTSIDE_DIR, IMPORT_PARAM_CONFLICT,
IMPORT_PAYLOAD_TOO_LARGE, IMPORT_DIR_NOT_CONFIGURED) plus a recovery
hint. Changing LIMESURVEY_IMPORT_DIR or LIMESURVEY_MAX_IMPORT_BYTES
requires a full restart of the MCP client process; reconnecting alone does not
reload environment variables.
import_survey returns the survey ID LimeSurvey actually used: it keeps the
ID embedded in the file when that ID is free, destination_survey_id
overrides it when set, and on an ID collision LimeSurvey silently assigns a
random 6-digit sid instead of failing.
Replacing a Question
set_question_properties cannot write question attributes, answer options, or
subquestions. limesurvey_replace_question (write scope content) swaps one
main question of an inactive survey for the question in a .lsq file, in
the same group and at the same position. Arguments: survey_id, question_id,
import_data or import_data_path (same rules as the imports above),
import_data_type (lsq), and confirm_destructive_action=true (required: the
old question is deleted). The code, type, texts, attributes, answer options,
and subquestions come from the file; the mandatory flag is read from the file
and passed on, because import_question always overwrites it.
The tool uses only official RemoteControl methods, in this order:
get_survey_properties (active must be N, otherwise SURVEY_ACTIVE),
get_question_properties (the question must belong to survey_id, otherwise
QUESTION_SURVEY_MISMATCH, and be a main question, otherwise
NOT_A_MAIN_QUESTION), list_questions, then the local parse of the file;
if the file has the same code, a temporary code for the old question
(set_question_properties), import_question, set_question_properties
(question_order of the old question), a read-back of the old question,
delete_question, and a verification (get_question_properties,
list_questions). The only question that can be deleted is question_id.
Every failure after the first write is rolled back: the question this call
imported is deleted and the old code is restored. The error
(REPLACE_QUESTION_FAILED) names the failed step and the rollback steps; if a
rollback step failed too, details.manual_cleanup lists what to fix by hand.
delete_question refuses a question that other questions depend on through
legacy conditions, which also rolls the replacement back. The result has
survey_id, group_id, old_question_id, new_question_id, title,
question_order, steps, verification, and notes. Question IDs change;
references by code (relevance expressions) keep working; legacy conditions that
reference the old question ID are not migrated.
Capability Detection
The server prints a startup preflight to stderr for every optional directory
(LIMESURVEY_EXPORT_DIR/LIMESURVEY_IMPORT_DIR/LIMESURVEY_THEME_DIR) that
is not configured, naming the tools that stay disabled until it is set and
that changing it requires a full restart.
limesurvey_get_instance_info makes no RemoteControl call by default: it
reports server_version, instance_host (host only, never credentials),
password_source (file or env; never the path or the content),
transport, read_only (true only for write scope none), write_scope and
write_scope_source (default, LIMESURVEY_WRITE_SCOPE or
LIMESURVEY_READ_ONLY), experimental_methods_enabled, per-directory
{configured, path, exists, writable} checks, and a capabilities summary.
capabilities stays a map of booleans (import_via_path,
export_survey_to_file, list_installed_themes, theme_generation,
theme_assignment, content_changes, lifecycle_changes,
participant_outreach, file_exports), computed after the write scope and
the configured directories. capability_blocked_by has exactly the same keys
and holds null when a capability is available, otherwise the reason (the
required and current write scope with its source, and/or the missing environment
variable; several reasons are joined with ; ).
Set probe_instance=true to additionally call list_surveys (connectivity/
auth proof, count only) and get_site_settings("versionnumber"), which
requires a superadmin service account and degrades to
permission_level: "standard" with instance_version: null otherwise. The
probe also fills server_time (ISO-8601 UTC) and server_time_source
("http_date_header"); without it both are null and server_time_hint says to
use probe_instance=true. server_time_note states that this is the web
server's clock in UTC, not a time zone (the PHP time zone is not readable
through RemoteControl). Call this before relying on
file export/import or theming tools.
Limits of RemoteControl
These gaps are in LimeSurvey 6.17.11 itself (verified against its source), not in this server:
No mail send log. The delivery state is only visible in the participant fields
sent,remindersent,remindercount, andemailstatus.No list of the survey's uploaded files (attachments, images).
get_uploaded_filesonly returns files that respondents uploaded in file upload questions.get_language_propertiesshows which server paths the mail attachments reference.No clock method. The server time is only available from the HTTP
Dateheader (get_instance_infowithprobe_instance=true). The server's PHP time zone is not readable through RemoteControl. Only thetimeadjustoffset (hours between web server time and local time) is readable, and only by superadmins throughget_site_settings('timeadjust').
limesurvey_list_installed_themes combines two best-effort signals, since
RemoteControl2 has no official method to enumerate installed themes:
generated_packages lists ZIPs/folders already generated locally in
LIMESURVEY_THEME_DIR, and themes_in_use lists the distinct template
values actually assigned to up to survey_scan_limit visible surveys (via
list_surveys + get_survey_properties), which works without a superadmin
account — "inherit" is tracked separately as inherit_count, not as a
theme. The response always includes the documented admin-UI fallback
(Configuration > Themes) for the complete list.
Experimental Extension
list_response_exports is not part of the official RemoteControl method list.
Its workflow tool is disabled unless the matching LimeSurvey extension is
installed and LIMESURVEY_ENABLE_EXPERIMENTAL_METHODS=true is set.
limesurvey_export_survey_to_file is likewise experimental: core LimeSurvey 6
RemoteControl has neither export_survey nor export_survey_structure
(verified against the LimeSurvey 6.17.11 source). The tool requires
LIMESURVEY_ENABLE_EXPERIMENTAL_METHODS=true, asks
export_survey_structure first and export_survey second, and only succeeds if
a plugin on the LimeSurvey side serves one of them; otherwise it fails with a
structured EXPORT_UNSUPPORTED error that lists why each method failed.
State of the art as of 2026-10-11 (research, see the CHANGELOG): there is no
verified LimeSurvey 6.x plugin that exports a .lss over RemoteControl. The
extendRemoteControl plugin only offers demo functions and declares LimeSurvey
3/4; RemoteManageResponse and rcAddReponseCode only handle responses; the
REST API (survey-detail) returns the editor's JSON model, not an .lss. The
RemoteControl handler class itself cannot be extended by a plugin, but a plugin
can answer additional methods on the core URL (the replaceDefaultLink pattern
of RemoteManageResponse), so an own small plugin offering
export_survey_structure(sessionKey, surveyId) returning the base64 .lss
works with this tool. Upstream, LimeSurvey pull request #5384 (bug #17747, open,
targeting the 7.x line) adds exactly that method.
Without an export, use limesurvey_verify_survey_against_lss (next section).
Comparing a Survey with a .lss File
limesurvey_verify_survey_against_lss(survey_id, lss_path[, language]) is a
read-only tool (write scope none) for checking an import or a hand-edited
survey against its source file. lss_path must point to a file inside
LIMESURVEY_IMPORT_DIR (or LIMESURVEY_EXPORT_DIR as a fallback; same path
check and size limit as import_data_path). The file is read locally; the live
survey is read with list_groups, list_questions, and
get_question_properties only, so read access to the survey content is enough
(get_survey_properties and its separate survey-settings permission are not
used). Without language, the base language is taken from the language field
of the list_groups rows. Answer options of dual-scale questions (type 1)
are requested as answeroptions_multiscale, which is the only name LimeSurvey
accepts for them, and compared per scale.
Groups (name and order), questions (code, type, mandatory, relevance, other,
text, help, position), subquestions, answer options, and question attributes
are matched by code, never by ID, because IDs change on import. The result has
summary (counts per area and attributes.missing_in_live, extra_in_live,
changed), differences (kind, group, question, item, field, lss,
live), differences_total, truncated (at most 500 differences are listed,
never cut silently), and limitations (conditions, quotas, assessments, default
values, and survey settings are not compared). language defaults to the base
language of the live survey. Both the LimeSurvey 6 file layout and older
exports with the texts in the entity rows are read.
Development
npm ci
npm test
npm run inspect
npm pack --dry-runThe 39 automated tests use mocked LimeSurvey JSON-RPC responses and cover:
JSON-RPC 1.0 ordering, session reuse, renewal, and secret handling
MCP handshake, schemas, annotations, confirmations, and read-only enforcement
Streamable HTTP bearer authentication and session isolation
workflow filtering and secure export files
survey theme ZIP generation, validation, publication guidance, and assignment
secure file imports via
import_data_pathfor survey, group, and question toolsenvironment preflight warnings (
envPreflightWarnings)capability detection (
get_instance_infowith and withoutprobe_instance,list_installed_themes) and the experimental, permission-degradingexport_survey_to_filetool
No live LimeSurvey credentials are required. Content evaluations must be created against a stable test instance; see evaluations/README.md.
An opt-in live integration runner exercises all 82 tools against disposable, prefixed test records:
npm run test:liveIt requires explicit environment confirmation and an external official
LimeSurvey fixture checkout. Never run it against a production instance.
cpd_importParticipants has no matching RemoteControl delete method, so the
runner reports the uniquely named central participant for manual removal. See
Live Integration Testing.
Project Structure
src/
client.ts JSON-RPC client and session handling
config.ts environment validation and secure defaults
tool-definitions.ts 56 official RemoteControl tools
workflow-tools.ts survey, participant, and export workflows
theme-tools.ts theme generator, validator, guide, and assignment
spec-tools.ts survey description (spec) tools
spec-generate.ts .lss generator (port of the plugin's Python generator)
spec-validate.ts spec validation with path, message, and fix
spec-read.ts reads a survey back as a spec (read methods only)
spec-compare.ts spec normal form, differences, fingerprint
scoped-client.ts per-call RemoteControl client limited to the write scope
attribute-defaults.ts question attribute defaults (generated, see tools/)
html-unescape.ts HTML entity decoding (port of Python's html.unescape)
server.ts MCP registration and central safety enforcement
http-server.ts authenticated Streamable HTTP transport
index.ts stdio/HTTP entry point
test/ mocked unit, protocol, transport, workflow, and theme tests
scripts/ opt-in guarded live integration test
tools/ generators for src/attribute-defaults.ts and src/html-entities.ts (not published)
docs/ detailed operational documentationCompatibility
Node.js 20, 22, and 24 are tested in CI.
RemoteControl uses JSON-RPC 1.0 positional parameters as required by LimeSurvey.
Theme generation supports LimeSurvey 7.x and 6.x with
vanilla; always validate against the exact installed patch release.LimeSurvey Cloud may restrict custom theme import by account or plan. The MCP server does not attempt unsupported filesystem installation.
Security
Read SECURITY.md before remote deployment. Report vulnerabilities privately via GitHub private vulnerability reporting, not through public issues.
Contributing
Contributions are welcome. See CONTRIBUTING.md and CHANGELOG.md.
License
The MCP server source code is licensed under the MIT License, Copyright (c) 2026 Wagner-Emden IT Services.
Survey theme ZIPs generated by the server are separately marked and licensed
under GPL-2.0-or-later because they are designed to inherit LimeSurvey's GPL
vanilla theme. Customer logos and other supplied assets retain their
own applicable rights and must not be redistributed without permission.
References
Available Tools
82 toolslimesurvey_activate_surveyActivate surveyA
Activate a survey after LimeSurvey consistency checks. Requires confirm_activation=true.
Calls LimeSurvey RemoteControl method activate_survey. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), confirm_activation (required), response_format, activation_settings. Returns: method, result, warnings, truncated, +1 more
limesurvey_activate_tokensActivate participant tableA
Create the survey participant table and optional custom attributes.
Calls LimeSurvey RemoteControl method activate_tokens. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), response_format, attribute_fields. Returns: method, result, warnings, truncated, +1 more
limesurvey_add_groupCreate question groupB
Add an empty question group to a survey.
Calls LimeSurvey RemoteControl method add_group. Authentication uses the configured service account; do not provide a session key.
Inputs: title (required), survey_id (required), description, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_add_group_from_specAdd a group from a descriptionA
Insert one new group with its questions into an inactive survey, described as a group spec (the format limesurvey_get_survey_spec returns at level group; every text is one string for all survey languages or a map per language). position is the 1-based place among the groups, { before: group_id } or { after: group_id }; without it the group goes to the end. The spec is checked against the survey first (its languages; every question code must be free in the whole survey, case ignored, because the import would rename it silently): SPEC_INVALID, CODE_CONFLICT, SURVEY_ACTIVE and POSITION_INVALID write nothing. The group is imported (import_group) with exactly the survey languages and only the new group is moved to its place; no other group is changed. It is then read back and compared with the spec. Returns { survey_id, group_id, position { index }, questions [{ code, question_id }], verification { ok, differences, differences_total, truncated }, side_effects, warnings }; a difference is a finding, not an error. If a step after the import fails, the new group is deleted again (nothing else) and ADD_GROUP_FAILED reports failed_step, rolled_back, manual_cleanup and cause_code. If the outcome of the import itself is unknown (lost answer, an unexpected answer), nothing is deleted: created is "unknown" and candidates and cleanup_hint say what to check. The .lsg import fills no translation gaps. An active survey is refused. A single question goes with limesurvey_add_question_from_spec. A Ranking question makes the tool read the LimeSurvey generation once (entries as subquestions on 7, as answers on 6). Needs the write scope content.
Inputs: group (required), survey_id (required), position. Returns: result, workflow
limesurvey_add_languageAdd survey languageB
Add a language to a survey.
Calls LimeSurvey RemoteControl method add_language. Authentication uses the configured service account; do not provide a session key.
Inputs: language (required), survey_id (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_add_participantAdd one survey participantC
Add one participant using a simple participant object.
Inputs: survey_id (required), participant (required), create_token. Returns: result, workflow
limesurvey_add_participantsAdd survey participantsA
Add one or more participants to a survey.
Calls LimeSurvey RemoteControl method add_participants. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), participants (required), create_token, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_add_question_from_specAdd a question from a descriptionA
Insert one new question into a group of an inactive survey, described as a question spec (the format limesurvey_get_survey_spec returns at level question; every text is one string for all survey languages or a map per language). position is the 1-based place in the group, { before: code } or { after: code }; without it the question goes to the end. The spec is checked against the survey first (its languages; the code must be free in the whole survey, case ignored): SPEC_INVALID, CODE_CONFLICT, SURVEY_ACTIVE, GROUP_SURVEY_MISMATCH and POSITION_INVALID write nothing. The question is imported (import_question) and only the new question is moved to its place; no other question is changed. It is then read back and compared with the spec. Returns { survey_id, group_id, question_id, code, position { index }, verification { ok, differences, differences_total, truncated }, side_effects, warnings }; a difference is a finding, not an error. import_question fills every text of the survey that has no row in an additional language with the base-language text, which cannot be undone: if the survey has such gaps, the tool answers TRANSLATION_GAPS (the gaps with path, language and question or group) and writes nothing, unless acknowledge contains fill_translation_gaps; side_effects then lists the filled gaps (paths as after the insertion). If a step after the import fails, the new question is deleted again (nothing else) and ADD_QUESTION_FAILED reports failed_step, rolled_back, manual_cleanup and cause_code. If the outcome of the import itself is unknown (lost answer, an error after the creation), nothing is deleted: created is "unknown" and candidates and cleanup_hint say what to check. An active survey is refused. A whole group goes with limesurvey_add_group_from_spec. A Ranking question makes the tool read the LimeSurvey generation once (entries as subquestions on 7, as answers on 6). Needs the write scope content.
Inputs: group_id (required), question (required), survey_id (required), position, +1 more. Returns: result, workflow
limesurvey_add_quotaCreate quotaB
Create a quota with minimum details.
Calls LimeSurvey RemoteControl method add_quota. Authentication uses the configured service account; do not provide a session key.
Inputs: name (required), limit (required), survey_id (required), url, +6 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_add_responseAdd survey responseA
Insert a response into a survey response table.
Calls LimeSurvey RemoteControl method add_response. Authentication uses the configured service account; do not provide a session key.
Inputs: response (required), survey_id (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_add_surveyCreate surveyA
Create an empty survey with minimum settings.
Calls LimeSurvey RemoteControl method add_survey. Authentication uses the configured service account; do not provide a session key.
Inputs: title (required), language (required), survey_id (required), format, +1 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_assign_survey_themeAssign an installed theme to a surveyAIdempotent
Assign an already imported LimeSurvey survey theme: read the current template (previous_theme), set the new one through set_survey_properties, and read it back with get_survey_properties. theme_name is the installed name (for a generated package its installed_theme_name, such as acme_feedback-100-ls7). LimeSurvey answers {"template": true} even when it keeps another theme; a different read-back value, or a refused save ({"template": false}), fails with THEME_NOT_APPLIED; a failed or empty read-back with THEME_NOT_VERIFIED (written: true); an unreadable previous theme with THEME_PREVIOUS_UNKNOWN (written: false). Results and THEME_NOT_APPLIED name previous_theme and changed. inherit is refused; set it with limesurvey_set_survey_properties or in the admin interface. This does not upload or install the theme package.
Inputs: survey_id (required), theme_name (required), confirm_theme_assignment (required). Returns: result, workflow
limesurvey_copy_surveyCopy surveyA
Copy an existing survey under a new name.
Calls LimeSurvey RemoteControl method copy_survey. Authentication uses the configured service account; do not provide a session key.
Inputs: new_name (required), source_survey_id (required), response_format, destination_survey_id. Returns: method, result, warnings, truncated, +1 more
limesurvey_cpd_importParticipantsImport central participantsA
Import records into the central participant database.
Calls LimeSurvey RemoteControl method cpd_importParticipants. Authentication uses the configured service account; do not provide a session key.
Inputs: participants (required), response_format, update_existing. Returns: method, result, warnings, truncated, +1 more
limesurvey_create_survey_from_specCreate a survey from a descriptionA
Create a new survey from a survey description (spec { survey, groups }). The spec is checked first: an invalid spec answers SPEC_INVALID with errors [{ path, message, fix }] and sends nothing to LimeSurvey. A valid spec becomes a LimeSurvey structure file (.lss) that import_survey imports; the new survey stays inactive and is not activated. The tool then reads the survey back (read methods only) and compares it with the spec. Returns { survey_id, title, languages, groups, questions, active, verification { ok, differences [{ path, expected, actual, and for a subquestion or answer its code and, on scale 1, scale_id }], differences_total, truncated }, truncated }, plus warnings, missing_translations and unreadable (each with a _total) when there are any. A list shows at most 200 entries and is cut further to stay within LIMESURVEY_MAX_RESPONSE_CHARS; the _total fields hold the full numbers and truncated says whether a list was cut. A difference is a finding of the comparison, not an error of the call. If LimeSurvey answers the import with an error, the tool answers CREATE_SURVEY_FAILED with LimeSurvey's message and details.created false (nothing was created). If the import call itself fails (transport or JSON-RPC error, or no survey ID in the answer), details.created is "unknown" with manual_cleanup, the title and a recovery that names limesurvey_find_surveys: look for the survey before calling again. If only the read-back fails, CREATE_SURVEY_FAILED names the created survey_id. The tool takes no file path, adds nothing to existing surveys, activates nothing and deletes nothing. A spec can be checked beforehand with limesurvey_validate_spec; limesurvey_get_survey_spec returns the spec of an existing survey in this format. A text is one string (for every language) or a map per language. A spec with a Ranking question makes the tool read the generation of the instance once (get_group_properties for group 0): on LimeSurvey 7 the entries are written as subquestions of type R (code up to 20 characters, with relevance), on LimeSurvey 6 as answers (code up to 5 characters, no relevance). The second scale of the types 1 (answers) and : and ; (subquestions, the columns) is given with scale_id 1. Needs the write scope content.
Inputs: spec (required). Returns: result, workflow
limesurvey_delete_groupDelete question groupADestructive
Delete a question group from a survey. Requires confirm_destructive_action=true.
Calls LimeSurvey RemoteControl method delete_group. Authentication uses the configured service account; do not provide a session key.
Inputs: group_id (required), survey_id (required), confirm_destructive_action (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_delete_languageDelete survey languageADestructive
Remove a non-base language from a survey. Requires confirm_destructive_action=true.
Calls LimeSurvey RemoteControl method delete_language. Authentication uses the configured service account; do not provide a session key.
Inputs: language (required), survey_id (required), confirm_destructive_action (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_delete_participantsDelete survey participantsADestructive
Delete participants by token-table row IDs. Requires confirm_destructive_action=true.
Calls LimeSurvey RemoteControl method delete_participants. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), token_ids (required), confirm_destructive_action (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_delete_questionDelete questionADestructive
Delete a question from its survey. Requires confirm_destructive_action=true.
Calls LimeSurvey RemoteControl method delete_question. Authentication uses the configured service account; do not provide a session key.
Inputs: question_id (required), confirm_destructive_action (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_delete_quotaDelete quotaADestructive
Delete a survey quota. Requires confirm_destructive_action=true.
Calls LimeSurvey RemoteControl method delete_quota. Authentication uses the configured service account; do not provide a session key.
Inputs: quota_id (required), confirm_destructive_action (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_delete_responseDelete survey responseADestructive
Permanently delete a response. Requires confirm_destructive_action=true.
Calls LimeSurvey RemoteControl method delete_response. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), response_id (required), confirm_destructive_action (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_delete_surveyDelete surveyADestructive
Permanently delete a survey. Requires confirm_destructive_action=true.
Calls LimeSurvey RemoteControl method delete_survey. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), confirm_destructive_action (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_export_responsesExport survey responsesARead-onlyIdempotent
Export responses as a base64-encoded document.
Calls LimeSurvey RemoteControl method export_responses. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), document_type (required), fields, heading_type, +7 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_export_responses_by_tokenExport responses by tokenARead-onlyIdempotent
Export responses for selected participant tokens as a base64-encoded document.
Calls LimeSurvey RemoteControl method export_responses_by_token. Authentication uses the configured service account; do not provide a session key.
Inputs: tokens (required), survey_id (required), document_type (required), fields, +5 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_export_responses_by_token_to_fileExport token responses to a fileB
Export responses for selected tokens and securely decode the result inside LIMESURVEY_EXPORT_DIR.
Inputs: tokens (required), survey_id (required), document_type (required), fields, +7 more. Returns: result, workflow
limesurvey_export_responses_to_fileExport responses to a fileC
Export responses and securely decode the base64 result inside LIMESURVEY_EXPORT_DIR.
Inputs: survey_id (required), document_type (required), fields, file_name, +9 more. Returns: result, workflow
limesurvey_export_statisticsExport survey statisticsARead-onlyIdempotent
Export survey statistics as a base64-encoded PDF, XLS, or HTML document.
Calls LimeSurvey RemoteControl method export_statistics. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), language, group_ids, document_type, +2 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_export_statistics_to_fileExport statistics to a fileB
Export survey statistics and securely decode the result inside LIMESURVEY_EXPORT_DIR.
Inputs: survey_id (required), language, file_name, group_ids, +4 more. Returns: result, workflow
limesurvey_export_survey_to_fileExport survey structure to a file (experimental)A
Attempt to export a survey's structure as .lss and write it inside LIMESURVEY_EXPORT_DIR, returning a path instead of base64. Core LimeSurvey 6 RemoteControl has neither export_survey nor export_survey_structure (verified against the LimeSurvey 6.17.11 source). The tool asks export_survey_structure(sessionKey, surveyId) first and export_survey(sessionKey, surveyId) second, so it only works if a plugin on the LimeSurvey side serves one of them; it requires LIMESURVEY_ENABLE_EXPERIMENTAL_METHODS=true and otherwise fails with EXPORT_UNSUPPORTED. Facts (checked 2026-10-11): no known 6.x plugin offers a structure export over RemoteControl (no verified plugin known); the RemoteControl handler class itself cannot be extended by a plugin, but a plugin can answer additional methods on the core URL (see LimeSurvey 6.17.11 source). Upstream, LimeSurvey pull request #5384 adds export_survey_structure for the 7.x line (open, not in any release); an own small plugin with that method works with this tool. Without an export, limesurvey_verify_survey_against_lss compares a .lss file with the live survey using read-only calls only.
Inputs: survey_id (required), file_name, overwrite, document_type, +1 more. Returns: result, workflow
limesurvey_export_timelineExport response timelineARead-onlyIdempotent
Return response counts by day or hour for a date range.
Calls LimeSurvey RemoteControl method export_timeline. Authentication uses the configured service account; do not provide a session key.
Inputs: end (required), start (required), period (required), survey_id (required), +1 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_find_surveysFind surveysARead-onlyIdempotent
Find visible surveys by ID or title with bounded client-side pagination.
Inputs: limit, query, offset. Returns: result, workflow
limesurvey_generate_survey_themeGenerate a responsive LimeSurvey survey themeA
Create a validated GPL-2.0-or-later ZIP theme that inherits the official Bootstrap 5 vanilla theme for LimeSurvey 7 or 6. LimeSurvey installs the theme under the ZIP file name without .zip and dots: the result's installed_theme_name (for example acme_feedback-100-ls7), at most 45 characters. Upload the ZIP unrenamed and assign that name.
Inputs: title (required), theme_name (required), author, density, +19 more. Returns: result, workflow
limesurvey_get_available_site_settingsList available site settingsARead-onlyIdempotent
List global setting names available to a super administrator.
Calls LimeSurvey RemoteControl method get_available_site_settings. Authentication uses the configured service account; do not provide a session key.
Inputs: response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_fieldmapGet survey field mapARead-onlyIdempotent
Return the survey response field map.
Calls LimeSurvey RemoteControl method get_fieldmap. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), language, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_group_propertiesGet group propertiesARead-onlyIdempotent
Read selected question-group properties. LimeSurvey identifies the group by group_id alone, so a wrong ID reads another survey's group. Pass the optional survey_id to cross-check: the result's sid must match, otherwise the call fails with GROUP_SURVEY_MISMATCH (survey_id is never sent to LimeSurvey).
Calls LimeSurvey RemoteControl method get_group_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: group_id (required), language, survey_id, properties, +1 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_instance_infoGet MCP server and LimeSurvey capability infoARead-onlyIdempotent
Report server-side configuration without any RemoteControl call by default: server_version, instance_host, password_source (file or env, never the path or the content), transport, read_only (true only for write scope none), write_scope and write_scope_source, experimental_methods_enabled, configured export/import/theme directories (each with a local exists/writable check), and a capabilities summary. capabilities are booleans computed after the write scope and the configuration; capability_blocked_by has the same keys and holds null (available) or the reason a capability is unavailable. Set probe_instance=true to additionally call list_surveys (connectivity/auth proof, count only) and get_site_settings("versionnumber") — the latter requires a superadmin service account and degrades to permission_level="standard" with instance_version=null otherwise. The probe also fills server_time (ISO-8601 UTC) and server_time_source ("http_date_header"): RemoteControl has no clock method, so the time comes from the HTTP Date header of the answer; without the probe both are null and server_time_hint says so. server_time_note explains that this is the web server's UTC clock, not the LimeSurvey time zone. Call this before relying on file export/import or theming tools.
Inputs: probe_instance. Returns: result, workflow
limesurvey_get_language_propertiesGet language propertiesARead-onlyIdempotent
Read localized survey properties. The attachments field is returned exactly as LimeSurvey stores it (a JSON string since DB version 647, a PHP serialize string on older instances; keep it unchanged for a round trip to set_language_properties). When it is part of the answer, attachments_parsed is added: { : [ { file_name, url, size, relevance } ] } with the mail types invitation, reminder, registration, confirmation, admin_notification and admin_detailed_notification; an empty value gives {} and an unparsable one gives null plus a warning. LimeSurvey drops requested property names that are not a column of the survey language settings without saying so: such names are listed in the warning unknown_fields (if every name is unknown the call fails with the no-data hint). An unknown or missing language silently falls back to the base language. RemoteControl has no method that lists the uploaded survey files themselves; attachments only references them by server path.
Calls LimeSurvey RemoteControl method get_language_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), language, properties, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_participant_propertiesGet participant propertiesARead-onlyIdempotent
Read selected properties for a participant matched by token or token-table ID.
Calls LimeSurvey RemoteControl method get_participant_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: query (required), survey_id (required), properties, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_participant_table_statusGet participant table statusARead-onlyIdempotent
Report whether a survey has a participant table, how many participants it holds, and whether the survey is closed-access. Read-only: get_summary(token_count) decides existence (a number means the table exists, the answer "No available data" means it does not), get_survey_properties adds access_mode, active, and allowregister on a best-effort basis. Closed access follows access_mode ("C") on LimeSurvey versions that have it; otherwise the existence of the participant table decides (closed_access_basis names which). The survey property usetokens is NOT evaluated by LimeSurvey 6.17.11 and is not used here. Without access_mode, a survey without a participant table has open access. Verified against the LimeSurvey 6.17.11 source; older releases may differ.
Inputs: survey_id (required). Returns: result, workflow
limesurvey_get_question_propertiesGet question propertiesARead-onlyIdempotent
Read selected question properties. LimeSurvey identifies the question by question_id alone, so a wrong ID reads another survey's question. Pass the optional survey_id to cross-check: the result's sid must match, otherwise the call fails with QUESTION_SURVEY_MISMATCH (survey_id is never sent to LimeSurvey).
Calls LimeSurvey RemoteControl method get_question_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: question_id (required), language, survey_id, properties, +1 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_quota_propertiesGet quota propertiesARead-onlyIdempotent
Read selected quota properties.
Calls LimeSurvey RemoteControl method get_quota_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: quota_id (required), language, properties, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_response_idsFind response IDsARead-onlyIdempotent
Find response IDs for a participant token.
Calls LimeSurvey RemoteControl method get_response_ids. Authentication uses the configured service account; do not provide a session key.
Inputs: token (required), survey_id (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_session_keyConnect to LimeSurveyA
Open and cache an authenticated RemoteControl session without exposing its key.
Calls LimeSurvey RemoteControl method get_session_key. Authentication uses the configured service account; do not provide a session key.
Inputs: response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_site_settingsGet site settingBRead-onlyIdempotent
Read one global LimeSurvey setting.
Calls LimeSurvey RemoteControl method get_site_settings. Authentication uses the configured service account; do not provide a session key.
Inputs: setting_name (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_summaryGet survey summaryARead-onlyIdempotent
Read response and participant summary counters. The answer "No available data" is not a call error: for token_* statistics it means the survey has no participant table (no participant statistics; error hint_code NO_PARTICIPANT_TABLE; access is decided by access_mode, check limesurvey_get_participant_table_status), for response statistics it means the survey has no response table: never activated or deactivated (hint_code NO_RESPONSE_TABLE). With statistic=all only the available parts are returned.
Calls LimeSurvey RemoteControl method get_summary. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), statistic, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_survey_languagesGet survey languagesARead-onlyIdempotent
Return the base and additional language codes configured for a survey.
Inputs: survey_id (required). Returns: result, workflow
limesurvey_get_survey_propertiesGet survey propertiesARead-onlyIdempotent
Read selected survey properties (any column of the surveys table; unknown names are dropped silently). usetokens is only a stored column in LimeSurvey 6.17.11: the core never evaluates it, so it neither tells whether a participant table exists nor whether the survey is closed. Closed access follows access_mode ("C" closed, "O" open) and the participant table; use limesurvey_get_participant_table_status for a ready-made answer. Verified against the LimeSurvey 6.17.11 source; older releases may differ.
Calls LimeSurvey RemoteControl method get_survey_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), properties, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_get_survey_specRead a survey, group or question as a descriptionARead-onlyIdempotent
Read a survey, one group or one question as a survey description (spec), with read methods only. With survey_id alone the whole survey is read (level survey); with group_id one group (level group); with question_id one question (level question); group_id and question_id exclude each other. Returns { level, survey_id, group_id (level group), question_id (level question), languages, active, spec, ids, position, fingerprint, unreadable [{ code, detail }], missing_translations [{ path, language }] }. spec has the format of limesurvey_create_survey_from_spec: level survey { survey, groups }, level group one group, level question one question; every text is a map per language, line breaks are \n and HTML entities are decoded except the markup characters; attribute values equal to the default of the question theme are left out; subquestions and answers come ordered by scale, and scale_id appears only for scale 1 (the columns of : and ;, the second answer scale of 1). spec holds no IDs: ids lists them by path (level survey: groups [{ path, group_id }] and questions [{ path, code, question_id }]; level group: group_id and questions; level question: question_id and group_id) and position gives the 1-based place of a group in the survey or of a question in its group. fingerprint is the SHA-256 of the spec. unreadable lists what RemoteControl cannot read and the spec therefore lacks (conditions of the old condition table, quota members, URL parameter assignments, stored attributes that the type, theme or a plugin does not define, archived response columns, at level survey the survey settings outside the spec, the default of the "Other" option of M and P questions, texts of a question that has no text row in a language); an entry that belongs to an element also has path and language. missing_translations lists the texts that have no row in a survey language, which the map then lacks. The spec can be checked with limesurvey_validate_spec and, at level survey, creates a copy with limesurvey_create_survey_from_spec. The tool never shortens the answer: if it would exceed LIMESURVEY_MAX_RESPONSE_CHARS it answers SPEC_TOO_LARGE with an outline (level survey: group_id, title, questions and estimated_chars per group) so that groups can be read one by one. An ID of another survey answers GROUP_SURVEY_MISMATCH or QUESTION_SURVEY_MISMATCH. The tool changes nothing and needs no write scope.
Inputs: survey_id (required), group_id, question_id. Returns: result, workflow
limesurvey_get_theme_publication_guideGet LimeSurvey theme publication instructionsARead-onlyIdempotent
Return version-aware installation, preview, assignment, accessibility, rollback, and optional community-publication steps for a survey theme, including installed_theme_name, the name LimeSurvey gives the package on import.
Inputs: hosting (required), theme_name (required), package_file_name (required), installed_limesurvey_version (required), +1 more. Returns: result, workflow
limesurvey_get_uploaded_filesGet uploaded response filesARead-onlyIdempotent
Return uploaded file metadata and base64 content for a token or response.
Calls LimeSurvey RemoteControl method get_uploaded_files. Authentication uses the configured service account; do not provide a session key.
Inputs: token (required), survey_id (required), response_id, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_import_groupImport question groupB
Import a question group into a survey. Use import_data_path for files at or above roughly 50 KB instead of inline import_data.
Calls LimeSurvey RemoteControl method import_group. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), import_data_type (required), import_data, new_group_name, +3 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_import_questionImport questionA
Import a question into a survey group. Use import_data_path for files at or above roughly 50 KB instead of inline import_data.
Calls LimeSurvey RemoteControl method import_question. Authentication uses the configured service account; do not provide a session key.
Inputs: group_id (required), survey_id (required), import_data_type (required), mandatory, +6 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_import_surveyImport surveyA
Import an LSA, CSV, TXT, or LSS survey. Use import_data_path for files at or above roughly 50 KB so the server reads and base64-encodes them itself; reserve inline import_data for small files under 200,000 characters of base64 text. The returned sid is the survey ID LimeSurvey actually used: it keeps the ID embedded in the file when that ID is free, destination_survey_id overrides it when set, and on an ID collision LimeSurvey silently assigns a random 6-digit sid instead of failing (verified against the LimeSurvey XMLImportSurvey/insertNewSurvey source).
Calls LimeSurvey RemoteControl method import_survey. Authentication uses the configured service account; do not provide a session key.
Inputs: import_data_type (required), import_data, new_survey_name, response_format, +2 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_invite_participantsInvite survey participantsA
Send survey invitation emails to selected or eligible participants. Preview first with dry_run=true: it sends nothing and never calls invite_participants, it simulates the selection from the participant list and reports would_receive and would_not_receive with a reason for every participant who is skipped (completed, already_invited, emailstatus_not_ok, invalid_email_address, not_valid_yet, expired, ...). Without continue_on_error LimeSurvey stops at the first participant whose validity window fails; the preview names that participant as stops_at_tid. The report stays within LIMESURVEY_MAX_RESPONSE_CHARS regardless of the table size: unselected participants (token_ids) are only counted as not_selected, and would_receive, would_not_receive and not_reached list at most 100 entries each (truncated_lists says which were cut, counts hold the full numbers). send_email=false is NOT a dry run: it resends the invitation to those who were already invited. Verified against the LimeSurvey 6.17.11 source; older releases may differ. Requires confirm_send_email=true unless dry_run=true.
Calls LimeSurvey RemoteControl method invite_participants. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), dry_run, token_ids, send_email, +4 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_list_filtered_participantsList filtered participantsBRead-onlyIdempotent
List participant rows with explicit filters, selected fields, and bounded pagination.
Inputs: survey_id (required), limit, offset, unused, +2 more. Returns: result, workflow
limesurvey_list_groupsList question groupsARead-onlyIdempotent
List question groups in a survey.
Calls LimeSurvey RemoteControl method list_groups. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), language, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_list_installed_themesList installed LimeSurvey themes (best effort)ARead-onlyIdempotent
LimeSurvey RemoteControl2 has no official method to enumerate installed survey themes (verified 2026-07-24 against api.limesurvey.org and the LimeSurvey source). This tool combines two best-effort signals instead: generated_packages lists ZIPs/folders already generated locally in LIMESURVEY_THEME_DIR, and themes_in_use lists the distinct template names actually assigned to surveys visible to this account (via list_surveys + get_survey_properties), which works without a superadmin account. Always includes the documented admin-UI fallback for the complete installed-theme list.
Inputs: survey_scan_limit. Returns: result, workflow
limesurvey_list_participantsList survey participantsARead-onlyIdempotent
List and filter survey participants with server-side pagination.
Calls LimeSurvey RemoteControl method list_participants. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), limit, start, unused, +3 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_list_questionsList questionsARead-onlyIdempotent
List questions and subquestions in a survey or group.
Calls LimeSurvey RemoteControl method list_questions. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), group_id, language, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_list_quotasList quotasARead-onlyIdempotent
List quotas configured for a survey.
Calls LimeSurvey RemoteControl method list_quotas. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_list_response_export_formatsList response export formatsARead-onlyIdempotent
Call the optional list_response_exports LimeSurvey extension to discover plugin-aware export formats.
Inputs: no named parameters. Returns: result, workflow
limesurvey_list_survey_groupsList survey groupsARead-onlyIdempotent
List survey groups visible to a user.
Calls LimeSurvey RemoteControl method list_survey_groups. Authentication uses the configured service account; do not provide a session key.
Inputs: username, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_list_surveysList surveysARead-onlyIdempotent
List surveys visible to a user, optionally filtered by survey group.
Calls LimeSurvey RemoteControl method list_surveys. Authentication uses the configured service account; do not provide a session key.
Inputs: username, response_format, survey_group_id. Returns: method, result, warnings, truncated, +1 more
limesurvey_list_usersList administration usersARead-onlyIdempotent
List administration users, optionally filtered by ID or username.
Calls LimeSurvey RemoteControl method list_users. Authentication uses the configured service account; do not provide a session key.
Inputs: user_id, username, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_mail_registered_participantsEmail registered participantsA
Send registration emails to survey participants. Requires confirm_send_email=true.
Calls LimeSurvey RemoteControl method mail_registered_participants. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), confirm_send_email (required), response_format, override_conditions. Returns: method, result, warnings, truncated, +1 more
limesurvey_release_session_keyDisconnect from LimeSurveyA
Release the cached RemoteControl session.
Calls LimeSurvey RemoteControl method release_session_key. Authentication uses the configured service account; do not provide a session key.
Inputs: response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_remind_participantsRemind survey participantsA
Send reminder emails to selected or eligible participants. Requires confirm_send_email=true.
Calls LimeSurvey RemoteControl method remind_participants. Authentication uses the configured service account; do not provide a session key.
Inputs: survey_id (required), confirm_send_email (required), token_ids, response_format, +3 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_replace_questionReplace a question with a .lsq fileADestructive
Replace one main question of an INACTIVE survey by the question in a .lsq file, in the same group and at the same position, using only official RemoteControl methods. This is how question attributes, answer options and subquestions are changed, because set_question_properties cannot write them. Steps: check that the survey is inactive (get_survey_properties); read the old question (get_question_properties; it must belong to survey_id and have parent_qid 0); read the group (list_questions); parse the file; if the file has the same code, give the old question a temporary code (set_question_properties); import_question (the new question goes to the end of the group; its mandatory flag is taken from the file because import_question always overwrites it); set_question_properties question_order to the old position; read the old question back and delete_question exactly that question; verify the result. The code, type, texts, attributes, answer options and subquestions come from the file (new_question_title is not offered). Any failure after the first write is rolled back (the question this call imported is deleted, the old code is restored); the error says which step failed and, if a rollback step failed too, lists manual_cleanup. The only question that can be deleted is question_id. Requires confirm_destructive_action=true and the write scope content. Question IDs change; references by code (relevance expressions) keep working; legacy conditions that reference the old question ID are not migrated, and delete_question refuses a question that other questions depend on through legacy conditions (the replacement is then rolled back). Exactly one of import_data (small base64 payload) or import_data_path (file inside LIMESURVEY_IMPORT_DIR) must be set.
Inputs: survey_id (required), question_id (required), confirm_destructive_action (required), import_data, +2 more. Returns: result, workflow
limesurvey_set_group_propertiesSet group propertiesA
Update question-group properties. Writable fields: group_order, randomization_group, grelevance, group_name, description. NOT writable through RemoteControl (the call is rejected before any request is sent): sid, gid, group_l10ns. A group cannot be moved to another survey or restructured through RemoteControl; re-import it (limesurvey_import_group with import_data_path) or use the LimeSurvey admin UI. Localized texts (group_name, description) need a language: {"language": "de", "group_name": "..."}. group_name and description are localized: pass them with data.language (this tool has no language parameter); the server moves them into questiongroupl10ns[language], so the other text field is never blanked. Keys LimeSurvey does not report back are returned in warnings. Verified against the LimeSurvey 6.17.11 source; older releases may differ.
Calls LimeSurvey RemoteControl method set_group_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: data (required), group_id (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_set_language_propertiesSet language propertiesA
Update localized survey properties. Writable fields: surveyls_title, surveyls_description, surveyls_welcometext, surveyls_endtext, surveyls_policy_notice, surveyls_policy_error, surveyls_policy_notice_label, surveyls_url, surveyls_urldescription, surveyls_email_invite_subj, surveyls_email_invite, surveyls_email_remind_subj, surveyls_email_remind, surveyls_email_register_subj, surveyls_email_register, surveyls_email_confirm_subj, surveyls_email_confirm, surveyls_dateformat, surveyls_attributecaptions, surveyls_alias, email_admin_notification_subj, email_admin_notification, email_admin_responses_subj, email_admin_responses, surveyls_numberformat, attachments. NOT writable through RemoteControl (the call is rejected before any request is sent): surveyls_language, surveyls_survey_id. Select the language row with the language parameter and send only the localized settings. LimeSurvey answers status OK even when single fields could not be saved; such fields are reported in warnings. Keys LimeSurvey does not report back are returned in warnings. Verified against the LimeSurvey 6.17.11 source; older releases may differ.
Calls LimeSurvey RemoteControl method set_language_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: data (required), survey_id (required), language, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_set_participant_propertiesSet participant propertiesA
Update a participant matched by token or token-table ID. Writable fields: participant_id, firstname, lastname, email, emailstatus, token, language, blacklisted, sent, remindersent, remindercount, completed, usesleft, validfrom, validuntil, mpid, attribute_N. NOT writable through RemoteControl (the call is rejected before any request is sent): tid. Participant rows are changed by token or tid in query; the participant table must exist (check limesurvey_get_participant_table_status). attribute_N stands for the custom attribute columns of the participant table (attribute_1, attribute_2, ...). Validation errors (for example an invalid email) are returned as an error. Keys LimeSurvey does not report back are returned in warnings. Verified against the LimeSurvey 6.17.11 source; older releases may differ.
Calls LimeSurvey RemoteControl method set_participant_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: data (required), query (required), survey_id (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_set_question_propertiesSet question propertiesA
Update question properties. Writable fields: title, preg, other, mandatory, encrypted, question_order, scale_id, same_default, relevance, question_theme_name, modulename, same_script, question, help, script. NOT writable through RemoteControl (the call is rejected before any request is sent): attributes, question_attributes, questionattributes, answers, answeroptions, answer_options, subquestions, defaultvalues, default_values, conditions, qid, gid, sid, parent_qid, type, question_l10ns. Question attributes, answer options and subquestions can only be changed by re-importing the question (limesurvey_import_question, or limesurvey_import_group / limesurvey_import_survey, all with import_data_path) or in the LimeSurvey admin UI; limesurvey_replace_question swaps a question of an inactive survey for the question in a .lsq file (inactive surveys only). Localized texts (question, help, script) are written with a language: {"language": "de", "question": "..."} or {"questionl10ns": {"de": {"question": "..."}}}. question, help and script are localized: pass them with data.language (or the language parameter); the server moves them into questionl10ns[language], so the other text fields are never blanked (LimeSurvey's legacy form would reset a field you did not send to an empty string). question_order is refused for questions that have legacy condition dependencies, and the group is renumbered after each change. Keys LimeSurvey does not report back are returned in warnings. Verified against the LimeSurvey 6.17.11 source; older releases may differ.
Calls LimeSurvey RemoteControl method set_question_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: data (required), question_id (required), language, response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_set_quota_propertiesSet quota propertiesA
Update quota properties. Writable fields: name, qlimit, action, active, autoload_url. NOT writable through RemoteControl (the call is rejected before any request is sent): id, sid, limit, quotals_message, quotals_url, quotals_urldescrip. Localized quota texts (message, URL, URL description) can only be edited in the LimeSurvey admin UI. Unknown keys are ignored silently by LimeSurvey; the server reports them in warnings. Keys LimeSurvey does not report back are returned in warnings. Verified against the LimeSurvey 6.17.11 source; older releases may differ.
Calls LimeSurvey RemoteControl method set_quota_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: data (required), quota_id (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_set_survey_propertiesSet survey propertiesA
Update editable survey properties. Writable fields: owner_id, gsid, admin, expires, startdate, adminemail, anonymized, format, savetimings, template, datestamp, usecookie, allowregister, allowsave, autonumber_start, autoredirect, allowprev, printanswers, ipaddr, ipanonymize, refurl, datecreated, showsurveypolicynotice, showregisterpolicy, showtokenpolicy, publicstatistics, publicgraphs, listpublic, htmlemail, sendconfirmation, tokenanswerspersistence, assessments, usecaptcha, usetokens, bounce_email, attributedescriptions, emailresponseto, emailnotificationto, tokenlength, showxquestions, showgroupinfo, shownoanswer, showqnumcode, bouncetime, bounceprocessing, bounceaccounttype, bounceaccounthost, bounceaccountpass, bounceaccountencryption, bounceaccountuser, showwelcome, showprogress, questionindex, navigationdelay, nokeyboard, alloweditaftercompletion, googleanalyticsstyle, googleanalyticsapikey, tokenencryptionoptions, access_mode, lastmodified. NOT writable through RemoteControl (the call is rejected before any request is sent): sid, active, language, additional_languages. Titles, descriptions and texts are per-language settings: use limesurvey_set_language_properties. Activation: limesurvey_activate_survey. Languages: limesurvey_add_language / limesurvey_delete_language. While the survey is active, anonymized, datestamp, savetimings, ipaddr and refurl are refused. access_mode and usetokens are plain column writes: they do not create or remove the participant table. Keys LimeSurvey does not report back are returned in warnings. Verified against the LimeSurvey 6.17.11 source; older releases may differ.
Calls LimeSurvey RemoteControl method set_survey_properties. Authentication uses the configured service account; do not provide a session key.
Inputs: data (required), survey_id (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_update_question_from_specChange a question to a described end stateADestructive
Change one existing question to the end state given as a question spec (typically the spec of limesurvey_get_survey_spec at level question, changed). The tool compares the end state with the question and picks the mode: none (nothing differs, nothing is written); texts (only question, help and subquestion texts: written in place with set_question_properties questionl10ns, also at an active survey); columns (code, mandatory, relevance, preg, other, same_default, same_script, encrypted, question_theme_name, modulename, inactive survey only: written in place, the question ID stays); replace (anything else: subquestions, answers and answer texts, attributes, defaults, type, script; inactive survey only): the end state is imported as a new question, moved to the place of the old one and read back completely; only if it matches is the old question deleted, otherwise the new one is deleted again and the old one keeps everything. Texts the end state does not change are written back as LimeSurvey stores them. dry_run true only reads (write scope none) and returns { survey_id, question_id, survey_active, mode (none, texts, columns, replace, or rejected when an active survey would need more than texts), changes [{ path, kind (text, column, structure), current, desired, and for a subquestion or answer its code and, on scale 1, scale_id }], changes_total, risks [{ code, blocking, acknowledgeable, detail, locations }], plan, fingerprint }. The real run needs expected_fingerprint (of get_survey_spec or the dry run; STALE_SPEC if the question changed since) and confirm_destructive_action true, and returns the same plus applied, verification { ok, differences } and, after a replacement, the new question_id and old_question_id. Blocking risks stop the call with UPDATE_QUESTION_BLOCKED before anything is written: qid_bound_links (every replacement: URL parameters, archived responses, quota memberships of the old ID), quota_members, other_default, removals, translation_gaps (import_question fills missing translations of the survey) and unreadable_texts (texts of the question that cannot be read in a language get the base-language text; both acknowledged with fill_translation_gaps) and answer_code_references can be acknowledged; code_references (the old code or removed fields such as CODE_SQ, CODE_SQcomment, CODE_other named anywhere, the end state of the question included; free texts are searched inside {...} only), sgqa_references and data_uri cannot. Each risk lists at most a part of its locations (locations_total). Errors: SPEC_INVALID, STALE_SPEC, SURVEY_ACTIVE (with the changes that need an inactive survey), UPDATE_QUESTION_BLOCKED, QUESTION_SURVEY_MISMATCH, REPLACE_QUESTION_FAILED (failed_step, rolled_back, manual_cleanup, differences), UPDATE_QUESTION_FAILED (texts and columns; the old values are written back and read back, manual_cleanup names what is not back), VERIFY_READ_FAILED (written: true; only the read-back failed). Texts of the survey, groups and questions alone go with limesurvey_update_survey_texts; a new question with limesurvey_add_question_from_spec. Needs the write scope content (dry run: none).
Inputs: question (required), survey_id (required), question_id (required), dry_run, +3 more. Returns: result, workflow
limesurvey_update_responseUpdate survey responseB
Update a response; include its response ID in the data.
Calls LimeSurvey RemoteControl method update_response. Authentication uses the configured service account; do not provide a session key.
Inputs: response (required), survey_id (required), response_format. Returns: method, result, warnings, truncated, +1 more
limesurvey_update_survey_textsChange texts of a surveyADestructiveIdempotent
Change texts of a survey by code, also at an active survey: survey title, description, welcometext and endtext (set_language_properties per language), group title and description by group_id (set_group_properties with questiongroupl10ns) and question, help and subquestion texts by question code (set_question_properties with questionl10ns on the question or subquestion). Every text is one string for every survey language or a map with some of them. Before anything is written the tool refuses: answers or attributes in texts (TEXT_NOT_WRITABLE: RemoteControl cannot write them; at an inactive survey use limesurvey_update_question_from_spec), an unknown code or a language the survey lacks (SPEC_INVALID with the path), a group of another survey (GROUP_SURVEY_MISMATCH), a row that holds an embedded data URI in any field, which LimeSurvey would remove on saving (DATA_URI_PRESENT), and an expected_fingerprint that does not match (STALE_SPEC). Returns { survey_id, survey_active, changes [{ path, language, current, desired }], changes_total, applied, verification { ok, differences }, side_effects (for example empty mail templates LimeSurvey fills on saving), collateral_changes (other fields of the saved rows that changed), fingerprint }. dry_run true only reads (write scope none) and shows the changes; its fingerprint can be passed as expected_fingerprint. If a write fails, every text the call wrote is reset and read back (TEXT_UPDATE_FAILED with rolled_back; manual_cleanup names the old values that are not back); if only the read-back after the writes fails, VERIFY_READ_FAILED says written: true. A subquestion, question or group named twice answers SPEC_INVALID. Needs the write scope content (dry run: none).
Inputs: texts (required), survey_id (required), dry_run, expected_fingerprint. Returns: result, workflow
limesurvey_upload_fileUpload response fileA
Upload a base64-encoded file for a file-upload question.
Calls LimeSurvey RemoteControl method upload_file. Authentication uses the configured service account; do not provide a session key.
Inputs: file_name (required), survey_id (required), field_name (required), file_content (required), +1 more. Returns: method, result, warnings, truncated, +1 more
limesurvey_validate_participantsValidate survey participantsARead-onlyIdempotent
Read-only check of the whole participant table before an invitation run: leading/trailing whitespace (email, firstname, lastname, token), duplicate email addresses (trimmed, case-insensitive) and tokens, address format (every address of a comma/semicolon list, with the pattern LimeSurvey's invite_participants uses), validfrom/validuntil against the server time, validfrom after validuntil, emailstatus other than OK, and missing email or token. Returns issues [{tid, field, code, detail}] and counts_by_code (codes WHITESPACE, DUPLICATE_EMAIL, DUPLICATE_TOKEN, INVALID_EMAIL, NOT_YET_VALID, EXPIRED, INVALID_VALIDITY_RANGE, EMAILSTATUS_NOT_OK, MISSING_EMAIL, MISSING_TOKEN). The server time is the HTTP Date header of the LimeSurvey answer; validfrom/validuntil are read in the server's local time, whose UTC offset is server_utc_offset_minutes or, without it, the timezone of the MCP host (time_basis says which). Entries within 60 minutes of the current time are listed under borderline. Uses only list_participants. The answer stays within LIMESURVEY_MAX_RESPONSE_CHARS: with too many issues, issues and borderline are cut (issues_truncated, issues_total) while counts_by_code stays complete.
Inputs: survey_id (required), server_utc_offset_minutes. Returns: result, workflow
limesurvey_validate_specValidate a survey descriptionARead-onlyIdempotent
Check a survey description (spec) and report every problem at once. kind says what the spec is: survey ({ survey, groups }), group (one group with its questions) or question (one question). Returns { valid, kind, errors [{ path, message, fix }], errors_total, warnings [{ path, message }], warnings_total, truncated, summary, checked_against_survey, skipped_checks }. errors and warnings show at most 200 entries and are cut further to stay within LIMESURVEY_MAX_RESPONSE_CHARS; errors_total and warnings_total hold the full numbers and truncated says whether a list was cut. Paths are 0-based, for example groups[1].questions[3].answers[0].code; for kind group and question they are relative to the checked object (for example code). The check covers keys, question codes (pattern, length, reserved words, duplicates), question types and the subquestions and answers each type needs, answer and subquestion codes, attribute names, attributes that some question theme defines but the theme of the question does not (plugin attributes and unknown themes are not checked), a question_theme_name of another question type, language codes (each once, none equal to the base language), survey.format, survey.expires (a real date and time), XML-forbidden characters and embedded data URIs. A text is one string (for every language) or a map per language; the map must name exactly the languages of the survey (a default value may name fewer); an empty question, subquestion or answer text is a warning. An attribute takes a map when it is stored per language (prefix, suffix, ...) or when no question theme lists it (a plugin attribute), not when it is known to be language independent. default is refused on questions with subquestions and on types R and |. An entry of a Ranking question may have a code of up to 20 characters and a relevance only on LimeSurvey 7: without survey_id this is a warning, with survey_id and kind group or question the version of the instance decides. Without survey_id nothing is sent to LimeSurvey and skipped_checks lists the checks that need the survey (for kind survey the languages come from the spec itself); with survey_id the tool reads the survey (read methods only) and also reports question codes that already exist in it and holds language maps to its languages. The types with a second scale are checked with their scale_id: type 1 needs subquestions (scale 0) and answers on scale 0 and 1, the types : and ; need subquestions on scale 0 (rows) and 1 (columns) and take no answers; codes are unique per scale; scale_id 1 elsewhere and default values on these three types are errors. The tool does not create or change anything; limesurvey_create_survey_from_spec creates a survey from a valid survey spec and limesurvey_get_survey_spec reads a survey, group or question as a spec.
Inputs: spec (required), kind, survey_id. Returns: result, workflow
limesurvey_validate_survey_themeValidate a generated LimeSurvey survey themeARead-onlyIdempotent
Validate a ZIP inside LIMESURVEY_THEME_DIR against the LimeSurvey 7.5.1 import: valid=true means LimeSurvey imports and uses the package. errors cover archive safety (more than 1000 entries, unsafe paths, size limits, CRC-32 mismatches, content signatures of images and fonts; the archive checks stop before anything is decompressed) and real import obstacles (installed name from the ZIP file name over 45 characters or with other characters, files the import would silently skip, a config.xml that is not well-formed or not at the root, a missing metadata/title or views/ directory). Warnings starting with "policy:" mark what LimeSurvey accepts but the generator does not produce, for example JavaScript, Twig templates, a parent other than vanilla, a missing css/mcp-theme.css, LICENSE.txt or GPL license, more than 50 entries, or external URLs in CSS; review them before the import. Returns installed_theme_name.
Inputs: file_name (required). Returns: result, workflow
limesurvey_verify_survey_against_lssCompare a survey with a .lss fileARead-onlyIdempotent
Read-only comparison of the live survey with a LimeSurvey structure file (.lss). The file must be inside LIMESURVEY_IMPORT_DIR (LIMESURVEY_EXPORT_DIR as a fallback; same path check and size limit as import_data_path). The live survey is read with list_groups, list_questions and get_question_properties only, so read access to the survey content is enough; without a language the base language is taken from list_groups. Groups (name and order), questions (code, type, mandatory, relevance, other, text, help, position), subquestions, answer options and question attributes are matched by code, never by ID, because IDs change on import. Returns { survey_id, lss_file, language, summary { groups, questions, subquestions, answers, attributes { missing_in_live, extra_in_live, changed } }, differences [{ kind, group, question, item, field, lss, live }], differences_total, truncated, limitations }. At most 500 differences are listed; truncated=true says more exist and differences_total holds the full number. limitations names what is not compared (conditions, quotas, assessments, ...). language defaults to the base language of the live survey. Use it to check an import or a hand-edited survey against its source file.
Inputs: lss_path (required), survey_id (required), language. Returns: result, workflow
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 82 tools
The 82 tools cover many distinct operations, but several groups overlap heavily: export_responses vs export_responses_to_file, export_responses_by_token variants, add_participants vs add_participant, list_participants vs list_filtered_participants, list_surveys vs find_surveys, and multiple text-update tools (set_language_properties, update_survey_texts, update_question_from_spec). Detailed descriptions help, but the sheer number and similarity make misselection likely.
Almost all tools follow the limesurvey_ prefix and snake_case verb_noun pattern. The main deviation is limesurvey_cpd_importParticipants (camelCase) and a few compound names like get_fieldmap, but these are minor.
82 tools is far beyond the 3–15 well-scoped range and exceeds even the 50+ extreme mismatch threshold. While LimeSurvey is complex and many operations map to RemoteControl methods, the count is unwieldy for an agent and suggests insufficient consolidation.
The surface covers CRUD for surveys, groups, questions, participants, responses, and quotas, plus import/export, spec-based creation/validation, themes, and instance info. Some gaps remain (e.g., direct condition/assessment management, single-response retrieval, user/permission CRUD), but workarounds exist via spec and replace tools.
Maintenance
Related MCP Connectors
MCP server for managing FormDesigner forms, fields, logic rules, themes, and entries
Screenshots, PDFs, image editing, QR codes, email validation and more through one hosted MCP server.
MCP server for the Seline Analytics API
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
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.-
- AlicenseNot gradedqualityFmaintenanceComprehensive MCP server for the Mautic marketing automation API, providing 203 tools for managing contacts, campaigns, emails, segments, and more.2ISC
- AlicenseBqualityDmaintenanceMCP server that exposes LimeSurvey's RemoteControl 2 JSON-RPC API as tools, enabling survey creation, activation, response export, and participant management through natural language.55MIT