npm package: @revuloop/mcp-server
Description: MCP server for Revuloop - create surveys, collect responses, and analyze results with AI assistants
Author: Revuloop
Latest version: 1.0.3

# @revuloop/mcp-server

MCP (Model Context Protocol) server for Revuloop. Lets AI assistants like Claude Desktop, Cursor, Windsurf, and n8n create surveys, collect responses, and analyze results directly.

## Setup

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
	"mcpServers": {
		"revuloop": {
			"command": "npx",
			"args": ["@revuloop/mcp-server"],
			"env": {
				"REVULOOP_API_KEY": "rlk_live_your_key_here"
			}
		}
	}
}
```

### Cursor / Windsurf

Add to your MCP settings:

```json
{
	"mcpServers": {
		"revuloop": {
			"command": "npx",
			"args": ["@revuloop/mcp-server"],
			"env": {
				"REVULOOP_API_KEY": "rlk_live_your_key_here"
			}
		}
	}
}
```

### n8n

Use the **MCP Client Tool** node in n8n:

1. Add an **MCP Client Tool** node to your workflow
2. Configure the connection:
   - **Command**: `npx`
   - **Arguments**: `@revuloop/mcp-server`
3. Set environment variables:
   - `REVULOOP_API_KEY`: Your API key
   - `REVULOOP_API_URL`: (optional) defaults to `https://revuloop.com`
4. Connect the MCP Client Tool node to an AI Agent node

### Claude Code

```bash
claude mcp add revuloop -- npx -y @revuloop/mcp-server
```

Then set the environment variable in your MCP config or shell:

```bash
export REVULOOP_API_KEY="rlk_live_your_key_here"
```

### Local Development

Point to your local Revuloop instance:

```json
{
	"mcpServers": {
		"revuloop": {
			"command": "node",
			"args": ["/path/to/packages/mcp-server/bin/cli.js"],
			"env": {
				"REVULOOP_API_KEY": "rlk_test_your_key_here",
				"REVULOOP_API_URL": "http://localhost:3000"
			}
		}
	}
}
```

## Getting Your API Key

1. Log in to your Revuloop dashboard
2. Go to **Settings > API Keys**
3. Click **Create New Key**
4. Copy the key (shown once only)

Requires a **BUSINESS** subscription for API access.

## Available Tools

### Surveys (9 tools)

| Tool              | Description                                                     |
| ----------------- | --------------------------------------------------------------- |
| `list_surveys`    | List surveys with status/type filter, workspace, and pagination |
| `create_survey`   | Create a survey with questions (starts as DRAFT)                |
| `generate_survey` | Generate a complete survey from a natural language description  |
| `get_survey`      | Get survey details including all questions and options          |
| `update_survey`   | Update survey title, description, or messages                   |
| `launch_survey`   | Launch a draft/paused survey to start collecting responses      |
| `pause_survey`    | Pause an active survey (can be relaunched)                      |
| `close_survey`    | Permanently close a survey                                      |
| `delete_survey`   | Delete a non-active survey                                      |

### Responses (5 tools)

| Tool               | Description                             |
| ------------------ | --------------------------------------- |
| `list_responses`   | Get paginated survey responses          |
| `get_response`     | Get a single response with all answers  |
| `submit_response`  | Submit a response to an active survey   |
| `export_responses` | Export responses as JSON, CSV, or Excel |
| `delete_response`  | Permanently delete a single response    |

### Analytics (5 tools)

| Tool                      | Description                                                     |
| ------------------------- | --------------------------------------------------------------- |
| `get_analytics`           | Get quantitative analytics (completion rates, NPS, trends)      |
| `get_analytics_overview`  | Unified entry point — auto-detects survey type, shows summary   |
| `get_ai_analytics`        | Get AI-generated analysis (themes, segments, recommendations)   |
| `generate_ai_analytics`   | Trigger AI-powered deep analysis (background job, uses credits) |
| `get_ai_analytics_status` | Poll background AI analysis job progress                        |

### Smart Surveys — AI-Powered (6 tools)

| Tool                        | Description                                               |
| --------------------------- | --------------------------------------------------------- |
| `create_smart_session`      | Start an AI conversational survey session                 |
| `respond_to_smart_question` | Answer a question (AI generates the next one)             |
| `complete_smart_session`    | Complete a smart survey session                           |
| `get_smart_analytics`       | Get smart survey analytics (quality, sentiment, sessions) |
| `list_smart_sessions`       | List sessions with quality scores and sentiment trends    |
| `get_smart_session`         | Get full conversation transcript for a session            |

### Webhooks (5 tools)

| Tool             | Description                            |
| ---------------- | -------------------------------------- |
| `list_webhooks`  | List webhook subscriptions with stats  |
| `create_webhook` | Subscribe to survey events (20+ types) |
| `update_webhook` | Modify a webhook (URL, events, active) |
| `test_webhook`   | Send a test payload to verify delivery |
| `delete_webhook` | Remove a webhook subscription          |

## Available Resources

| Resource                                   | Description                                 |
| ------------------------------------------ | ------------------------------------------- |
| `revuloop://surveys`                       | All surveys with status and response counts |
| `revuloop://surveys/{id}`                  | Full survey detail with questions           |
| `revuloop://surveys/{id}/analytics`        | Quantitative survey analytics               |
| `revuloop://surveys/{id}/responses/recent` | Last 10 responses                           |
| `revuloop://surveys/{id}/analytics/ai`     | AI-generated analysis and insights          |
| `revuloop://surveys/{id}/analytics/smart`  | Smart survey analytics overview             |

## Available Prompts

| Prompt                   | Description                                            |
| ------------------------ | ------------------------------------------------------ |
| `create-survey`          | Guided workflow: generate a survey, review, and launch |
| `analyze-responses`      | Guided workflow: fetch analytics, AI analysis, export  |
| `explore-smart-sessions` | Guided workflow: browse sessions, read transcripts     |

## Environment Variables

| Variable           | Required | Default                | Description           |
| ------------------ | -------- | ---------------------- | --------------------- |
| `REVULOOP_API_KEY` | Yes      | —                      | Your Revuloop API key |
| `REVULOOP_API_URL` | No       | `https://revuloop.com` | API base URL          |

## Example Workflows

**"Create a customer feedback survey and launch it"**

1. AI calls `generate_survey` with a natural language prompt
2. AI shows you the generated questions and links
3. AI calls `launch_survey` to make it live

**"How are my surveys performing?"**

1. AI reads `revuloop://surveys` resource for an overview
2. AI calls `get_analytics` for detailed stats on specific surveys

**"Analyze the responses to my NPS survey"**

1. AI calls `get_analytics_overview` to check survey type and response count
2. AI calls `generate_ai_analytics` to trigger deep analysis
3. AI polls `get_ai_analytics_status` until complete
4. AI calls `get_ai_analytics` for themes, patterns, and recommendations

**"Explore my smart survey conversations"**

1. AI calls `get_smart_analytics` for session overview and quality scores
2. AI calls `list_smart_sessions` to show recent conversations
3. AI calls `get_smart_session` to read a full conversation transcript