# SurveySparrow MCP

> SurveySparrow connects conversational survey data collection with your agent workflow. It lets you list surveys, analyze submissions by status, and manage CRM contacts all from a single chat interface.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** conversational-surveys, experience-management, feedback-collection, audience-management, multi-channel-feedback, customer-experience

## Description

Connecting **SurveySparrow** to your AI client gives you immediate control over how you collect feedback and manage contacts. You can handle the whole workflow—from gathering survey data to updating CRM records—all within a single chat interface.

**Managing Your Audience Directory (CRM Contacts)**
You gotta keep track of who you're talking to, right? With this server, you control every contact record in your audience directory. Want to add someone new? You can run `create_contact` and dump a fresh record into the system. Need to find out what details you already have on an existing client? Just ask for their info using `get_contact_info`, giving it your unique ID or any criteria you've got. If someone's contact data is outdated, don't worry; you can run `remove_contact` and wipe that record permanently from the directory. You can also peep at what existing lists are set up by calling `list_contact_folders`, which pulls a list of all your organized contact groups. To see who's in the main system, simply ask for all contacts using `list_crm_contacts`. 

**Analyzing Survey Submissions and User Engagement**
Tracking responses is key. You can get a full rundown of every survey you've set up by calling `list_surveys`, which pulls a list of every conversational survey in your account. If you need to know what questions are inside one of those surveys, use `get_survey_details` for general info, or run `get_survey_questions` to see the specific fields and structure. When it comes to submissions, you can list all submitted responses using `list_survey_responses`. Better yet, you can filter that massive list by completion status—you'll get everything marked as either started or fully completed. This lets you track engagement without ever leaving your chat window.

**Tracking Campaigns and Account Status**
Did someone actually get the link? You can check out the history of sent invites and email shares using `list_email_shares` to verify campaign distribution. To make sure your automated workflows are firing correctly, you can list all active webhooks by calling `list_active_webhooks`, confirming exactly which events have notification set-ups. For a full picture of your setup, the server lets you check general account settings and region details via `get_user_profile`. This gives you visibility into both your operational status and how the system is configured.

## Tools

### create_contact
Adds a new contact record into your SurveySparrow audience directory.

### remove_contact
Permanently deletes a contact record from the audience directory.

### get_user_profile
Retrieves general account and user profile information, including region settings.

### get_contact_info
Retrieves specific details for an existing contact using their unique ID or criteria.

### get_survey_questions
Lists the specific fields or questions contained within a given survey structure.

### get_survey_details
Fetches high-level metadata and general information about a specified survey.

### list_contact_folders
Retrieves a list of existing contact lists or folders in your CRM directory.

### list_crm_contacts
Lists all contacts currently stored in your main audience management system.

### list_survey_responses
Lists all submitted survey responses, allowing filtering by completion status (started or completed).

### list_email_shares
Retrieves a history of sent survey invitations and email shares for tracking purposes.

### list_surveys
Retrieves a list of every conversational survey set up in your account.

### list_active_webhooks
Lists all active webhooks to verify which events are configured for notifications.

## Prompt Examples

**Prompt:** 
```
List all active surveys in my SurveySparrow account.
```

**Response:** 
```
I've retrieved your surveys. You have 3 active conversational surveys: 'Customer Effort Score', 'Product Pulse Check', and 'New Feature Survey'. Which one would you like to see responses for?
```

**Prompt:** 
```
Show me the last 5 responses for the 'Customer Effort Score' survey.
```

**Response:** 
```
I've fetched the latest responses. There are 5 recent submissions. Completion rate is 80%, with most users taking about 2 minutes to finish. Shall I retrieve the detailed answers?
```

**Prompt:** 
```
Search for a contact with the email 'jane.doe@example.com'.
```

**Response:** 
```
I've found the record. Jane Doe (ID: cont_10293) is a registered contact in your CRM. She is currently in the 'Loyal Customers' list. Would you like to see her full survey history?
```

## Capabilities

### Manage CRM Contacts
Creates, retrieves details for, lists, and deletes contacts in your audience directory.

### Analyze Survey Submissions
Lists all survey responses and filters them by completion status to track overall user engagement.

### Inspect Survey Structure
Retrieves details about specific surveys or lists all available conversational surveys in your account.

### Track Campaign Distribution
Lists past survey invitations and checks the status of active webhooks for workflow confirmation.

### View Account Status
Checks general account settings, region details, and contact lifecycle management directly through commands.

## Use Cases

### Auditing a Campaign Failure
The operations team suspects a survey isn't reaching certain users. They ask the agent to run `list_crm_contacts` and filter by 'unsubscribed'. Then, they use `list_email_shares` to see which groups were missed, immediately identifying the contact list gap.

### Analyzing Post-Launch Sentiment
The CX Manager needs a quick sentiment check on a new feature. They ask for responses using `list_survey_responses`, filtering only for 'completed' submissions. The agent returns the total count and average time spent, allowing them to know if the launch hit its target engagement rate.

### Cleaning Up Stale Data
A Marketing Analyst discovers old contacts that are no longer relevant. They run `list_crm_contacts` to find the stale records and then use `remove_contact` on specific IDs, keeping the audience directory clean for future campaigns.

### Validating System Setup
An engineer needs to know if their survey data is triggering external alerts. They run `list_active_webhooks`, verify the correct webhook exists, and use `get_user_profile` to confirm the regional settings match the expected deployment zone.

## Benefits

- See who's completed a survey instantly. Use `list_survey_responses` to filter submissions by status, giving you immediate visibility into completion rates for specific campaigns.
- Manage your CRM audience without leaving the chat. You can use `create_contact` or `get_contact_info` to verify user records before running an outreach campaign.
- Audit automated workflows easily. Call `list_active_webhooks` to confirm every event-driven notification is firing as expected, preventing data gaps.
- Understand survey design flaws fast. Run `get_survey_questions` on a specific survey ID to quickly list all fields and see if the question structure needs tweaking.
- Track campaign reach end-to-end. Use `list_email_shares` to verify exactly how many times an invitation was sent, linking outreach volume back to conversion data.

## How It Works

The bottom line is: your AI client acts as a single dashboard, letting you manage all feedback and contact data without logging into SurveySparrow itself.

1. First, subscribe to the server. Then, you must enter your SurveySparrow Access Token and select your operational region (e.g., US or EU).
2. Next, tell your agent what data you need—for example: 'Show me all completed responses for the Product Pulse Check survey.'
3. The agent calls the necessary tool(s), fetches the raw data, and presents a clean summary back to you in plain text.

## Frequently Asked Questions

**How do I see all the available surveys using list_surveys?**
You run `list_surveys` to get an indexed list of every survey in your account. This function provides metadata for each one, helping you pick the right ID for analysis.

**Can I check if a contact exists before running a campaign? Use get_contact_info.**
Yes. Running `get_contact_info` allows your agent to verify that the contact record is active and available in the CRM using their ID or email address.

**What status can I filter responses by? list_survey_responses**
You can filter submissions by 'completed' or 'started'. This distinction lets you separate finalized data from users who abandoned the survey process early on.

**Where do I find out what questions a specific survey has? get_survey_questions**
Use `get_survey_questions` and provide the target survey ID. This returns a detailed list of every field, including text box types and mandatory status.

**How do I check if my webhooks are working correctly? list_active_webhooks**
Call `list_active_webhooks`. This shows all active notification endpoints configured in your account, letting you verify that event-driven workflows remain online.

**How do I check all available contact lists before running a campaign? Use list_contact_folders.**
Running list_contact_folders returns a list of every segment or folder you've created. This lets you see which groups of contacts are ready for targeted outreach.

**If I need to delete an old contact, how do I use the remove_contact tool?**
You must provide the unique contact ID to the remove_contact tool. This action permanently deletes the record from your CRM; always confirm the ID before running it.

**What specific metadata can I get using get_survey_details?**
get_survey_details retrieves the core configuration data for a survey. You'll find details like its creation date, last modification timestamp, and overall active status.

**Can I see all the questions in a survey via AI?**
Yes! Use the `get_survey_questions` tool and provide the Survey ID. Your agent will retrieve the complete structure, including labels and field types.

**How do I list all the contacts stored in my account?**
Run the `list_crm_contacts` query. The agent will retrieve a list of all audience members stored in your SurveySparrow account.

**Is it possible to see the status of survey responses (started vs completed)?**
Absolutely. Use the `list_survey_responses` tool and provide the Survey ID. You can pass the optional `state` parameter to filter by completion status.