SurveyNinja

Quick start | Skills | Tools | What to ask | Connecting

The SurveyNinja MCP server and ready-made skills for your AI assistant. Describe a survey in plain words and the assistant builds it in your account, checks it before launch, reads the responses and prepares a report you can send.

Works in Claude, ChatGPT, Claude Code, Cursor, VS Code, Codex, Gemini CLI and other assistants that connect to remote MCP servers. Every SurveyNinja plan includes it, Free too.

You:  Build a survey for our repair shop customers: rate the work and collect
      contacts for a follow-up visit.
AI:   ✓ picked question types  ✓ built 7 questions and 2 branches  ✓ applied a theme
      The draft is ready and does not open by its link yet. Publish it?

Quick start

1. Have a SurveyNinja account. Sign up for free if you don't have one.
2. Add the server https://mcp.surveyninja.io/mcp/v1 to your assistant. Steps for each assistant are below.
3. Allow access. Sign in to SurveyNinja when the assistant asks, choose a workspace and click Allow access. Most assistants need no key; for the rest, use an API key as shown below.
4. Ask: “Show my surveys and how many responses came in this week.”

Claude Code: everything in one install

The plugin adds the MCP server and every skill at once:

/plugin marketplace add surveyninjaio/surveyninja-mcp
/plugin install surveyninja@surveyninja

Then type /mcp, select the SurveyNinja server and sign in. The plugin is the plugin/ folder: the server and a copy of the skills, nothing else. Only the server, without the skills:

claude mcp add --transport http surveyninja https://mcp.surveyninja.io/mcp/v1

Claude and ChatGPT

Claude on the web or in the desktop app: Settings → Connectors → Add custom connector. Enter a name, for example SurveyNinja, and the server address, click Add, then Connect, and allow access in SurveyNinja. On Claude Team and Enterprise an organization owner adds the connector first, then each member connects it.

ChatGPT: turn on developer mode in the ChatGPT settings (it is available on some ChatGPT plans), create a connector with the server address and OAuth authentication, then allow access in SurveyNinja.

Other assistants

One click:

Cursor

Add the server to ~/.cursor/mcp.json for all projects, or to .cursor/mcp.json for one project, then open the MCP section in the Cursor settings and sign in to the surveyninja server:

{
  "mcpServers": {
    "surveyninja": {
      "url": "https://mcp.surveyninja.io/mcp/v1"
    }
  }
}

VS Code

Add the server to .vscode/mcp.json in your project, start it from the file and sign in when VS Code asks. The server works in GitHub Copilot Chat in agent mode.

{
  "servers": {
    "surveyninja": {
      "type": "http",
      "url": "https://mcp.surveyninja.io/mcp/v1"
    }
  }
}

Gemini CLI

As an extension, with the server and the skills at once:

gemini extensions install https://github.com/surveyninjaio/surveyninja-mcp

Or only the server, in ~/.gemini/settings.json:

{
  "mcpServers": {
    "surveyninja": {
      "httpUrl": "https://mcp.surveyninja.io/mcp/v1"
    }
  }
}

If Gemini CLI does not offer to sign in by itself, run /mcp auth surveyninja.

Codex

Add the server to ~/.codex/config.toml:

[mcp_servers.surveyninja]
url = "https://mcp.surveyninja.io/mcp/v1"

Then run codex mcp login surveyninja: SurveyNinja opens in the browser, and you click Allow access. No key goes into the file. In the Codex app, add the server under Settings → MCP servers as Streamable HTTP and select Authenticate.

Any other client

Any client that connects to remote MCP servers over Streamable HTTP can use the same address. If it supports MCP sign-in (OAuth), it opens SurveyNinja for you to allow access. If it does not, pass an API key in a header:

Authorization: Bearer YOUR_API_KEY

The same configs as files are in clients/, and every step with troubleshooting is in docs/connect.md.

At a glance

What it can do

Surveys. Create a survey from scratch, from a template or with AI. Edit questions, logic, design and settings, then publish.

Responses. Read responses, tag them and keep the account clean.

Reports. Summary, report, report with filters and AI report. Exports to CSV, Excel, Word, SPSS and PDF, public links to share results.

Delivery. Notifications, webhooks, integrations and invitations to the team.

The full list by section is in docs/tools.md, starter phrases in docs/prompts.md.

Skills

A skill is a ready-made playbook for the assistant. You ask “sort out the open-ended answers”, and the skill tells it which tools to call, in what order and how to present the result. Skills are text instructions with no code: nothing gets installed or run. Each one is also on surveyninja.io/skills with examples of the result.

Build and share

| Skill | What you get | Download | |---|---|:-:| | Build a survey from a brief | Describe what you need in plain words, and the assistant builds the survey in your SurveyNinja account as a draft | ZIP | | Skip logic and branching | Sets up survey logic so that no respondent ever hits a dead end | ZIP | | Rewrite survey copy | Rewrites your questions so people finish the survey, starting from the data rather than taste | ZIP | | Distribute the survey | Gets the survey ready to hand out so you can still tell which channel each response came from | ZIP | | Launch kit | Puts the whole launch together at once: labeled links, announcement copy for each channel and a QR code | ZIP |

Check before launch

| Skill | What you get | Download | |---|---|:-:| | Pre-launch check | Finds what will break on real respondents while the link is still unsent | ZIP | | Data quality check | Tells you whether the responses can be trusted before anyone builds conclusions on them | ZIP |

Understand results

| Skill | What you get | Download | |---|---|:-:| | Survey results summary | Answers "so what did the survey say" with figures and a conclusion instead of a raw export | ZIP | | Analyze open-ended answers | Turns a hundred lines of free text into a handful of themes with numbers and quotes | ZIP | | Completion funnel | Shows which question makes people close the tab, and why | ZIP | | A/B variant analysis | Tells you whether the difference between variants is real or just noise | ZIP | | Comparing with past results | Compares a survey with its own past, because one figure means little and a change says a lot | ZIP | | How many responses you need | Tells you whether what you have is enough and how many more responses you need before conclusions hold | ZIP | | Survey timeline | Answers “why did responses stop” by lining up collection against the edit history | ZIP | | Comparing traffic sources | Shows which channel brought the right people and which only brought numbers | ZIP | | Results for the client | Turns survey results into something you can send: a link, a file or a report with conclusions | ZIP | | Report and survey styling | Tidies up what people see from outside: the survey theme, the report colors and the logo | ZIP |

Deliver responses

| Skill | What you get | Download | |---|---|:-:| | New response notifications | Sets up where new responses are announced, by email or in Telegram, and fixes it when they stop arriving | ZIP | | Webhook setup | Sends survey responses to your own address and checks that the receiver accepted them | ZIP | | Why responses are not delivered | Finds why responses never reach your Telegram, Google Sheet, Zapier or webhook, and what to do about it | ZIP | | Lead quality | Counts the people who left a contact you can actually use | ZIP |

Keep the account tidy

| Skill | What you get | Download | |---|---|:-:| | Workspace audit | Shows in one report where your workspace is losing responses, storage and attention | ZIP | | Tidying up the account | Sorts, archives, copies and cleans, and knows which of those cannot be undone | ZIP | | Members and access | Finds out why a colleague cannot see the surveys and grants exactly the rights they need | ZIP | | Cleaning up responses | Removes test runs and duplicates from your results and shows you the list before anything goes | ZIP |

All skills in one archive: all.zip.

Installing skills without the plugin

One command for any assistant: skills finds the agents you have installed and asks where to put the skills.

npx skills add surveyninjaio/surveyninja-mcp

Or unzip an archive into the folder your assistant reads skills from and restart it: .claude/skills/ for Claude Code, .agents/skills/ for Codex and Cursor, .gemini/skills/ for Gemini CLI. More in skills/README.md.

Security

• With Allow access the assistant works in the one workspace you chose and loses access when you leave it or remove the connector. An API key stops working the moment you delete it in Settings → API / MCP.
• Tools that delete or overwrite data, such as deleting responses, carry the destructiveHint annotation, so your client can ask before it calls them. Read what the assistant is about to do before you confirm.
• Every skill has a “What not to do” section: things the assistant must not do without your word.
• There are no secrets in this repository. Configs use YOUR_API_KEY as a placeholder. Found something that looks like a real key, or a security issue? See SECURITY.md.

Privacy

The plugin and the skills run nothing on your computer: the skills are text instructions, and the plugin only adds the server address to your client. The one connection is to https://mcp.surveyninja.io/mcp/v1 over HTTPS, and it carries what your assistant asks for: your surveys, responses and reports in your SurveyNinja account. SurveyNinja stores that data on a server in the EU behind Cloudflare and handles it under the privacy policy.

Links

• SurveyNinja
• MCP server page
• Skills catalog
• MCP and API documentation
• LinkedIn

License

MIT, see LICENSE. The license covers what is in this repository: documentation, configs and skills. The SurveyNinja service itself is provided under its user agreement.