# limesurvey-mcp

*[Leer en español](./README.es.md)*

**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`](https://github.com/pmanciniq/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](https://pipx.pypa.io/) is recommended for installing it in
an isolated environment without managing venvs by hand:

```bash
pipx install limesurvey-mcp
```

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

```bash
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:

```bash
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`](./.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):

```json
{
  "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

```bash
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](./LICENSE).