limesurvey-mcp

Leer en español

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

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

Features

• Automatic session handling: credentials come from your configuration; the session key is obtained, cached, and renewed automatically. The MCP client never handles sSessionKey.
• Files by path: import methods (import_survey, import_group, import_question, upload_file) accept file_path; export methods (export_responses, export_statistics, ...) accept output_path. The server base64-encodes/decodes for you — it never dumps large files into the LLM's context. The same methods also accept base64 content sent directly over HTTP.
• Actionable errors: API failures come back as ERROR: ... text with the error code (ERR_NO_PERMISSION, ERR_INVALID_SURVEY, ...) instead of a stack trace.
• Full coverage of the RemoteControl 2 API: surveys, groups, questions, languages, participants/tokens, responses, quotas, users.

Installation

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

pipx install limesurvey-mcp

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

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

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

Configuration

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

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

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

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

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

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

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

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

Registering the server with your MCP client

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

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

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

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

Security

• The server operates against a real LimeSurvey instance. delete_survey, delete_group, delete_question, delete_response, delete_participants, and activate_survey are destructive or hard to reverse.
• invite_participants, remind_participants, and mail_registered_participants send real emails.
• The .env file (if you use one) contains credentials: don't commit it to version control (.gitignore already excludes it) or share it in plain text.
• Prefer testing against a test instance/survey before pointing at production.

Local development

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

License

MIT. See LICENSE.