Userology MCP Server
OfficialAllows analyzing Figma prototypes by extracting screen context from Figma files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Userology MCP Server Create a new UX study to test the checkout flow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Userology MCP Server
An MCP (Model Context Protocol) server that exposes the Userology UX research platform as tools and resources for any MCP-compatible AI client — Claude Desktop, Cursor, Windsurf, and more.
What It Does
This server wraps the Userology researcher-service REST API, giving AI assistants the ability to:
Create & manage studies — Draft, launch, copy, and configure UX research studies
Build interview guides — AI-generate, edit, and rephrase interview guides
Manage sections/tasks — Add prototype testing, concept testing, voice interview, and live product research sections
Access analytics — Get qualitative insights, quantitative metrics, Q&A analysis, and full study reports
Use Synthesis Studio — Have AI-powered conversations to explore research findings
View session data — Access participant lists, session transcripts, and recordings
Analyze Figma prototypes — Extract screen context from Figma files
Related MCP server: YouTrack MCP Server
Quick Start
1. Install
cd userology-mcp-server
pip install -e .2. Configure
Copy .env.example to .env and fill in your credentials:
cp .env.example .envRequired variables:
Variable | Description |
| Researcher-service API URL (default: |
| Your organization's tenant ID |
| Firebase JWT token (interactive mode) |
3. Add to Claude Desktop
Add this to your claude_desktop_config.json:
{
"mcpServers": {
"userology": {
"command": "userology-mcp",
"env": {
"USEROLOGY_TENANT_ID": "your-tenant-id",
"USEROLOGY_ID_TOKEN": "your-token"
}
}
}
}4. Test with MCP Inspector
npx @modelcontextprotocol/inspector userology-mcpAvailable Tools (45 total)
Study Management (9 tools)
create_study · create_study_from_description · get_study · list_studies · update_study_name · update_study_details · update_study_status · copy_study · delete_study
Section/Task Management (7 tools)
create_section · get_sections · get_section · update_section · delete_section · copy_section · reorder_section
Interview Guides (4 tools)
get_interview_guides · update_interview_guide · generate_guide · rephrase_guide
Analytics & Reports (11 tools)
get_analytics_status · generate_analytics · get_qualitative_insights · get_quantitative_data · get_qna_analysis · get_study_summary · get_study_insights · get_study_report · generate_study_report · get_session_report · get_ui_annotations
Synthesis Studio (6 tools)
create_synthesis_chat · list_synthesis_chats · get_synthesis_chat · send_synthesis_message · delete_synthesis_chat · share_synthesis_chat
Session & Participant Data (7 tools)
get_participants · get_session · get_session_recordings · get_sessions_report · get_participant_sessions_report · get_study_tags · update_study_tags
Figma Integration (1 tool)
get_figma_context
Resources
URI | Description |
| List all studies |
| Study details |
| Interview guides |
| Analytics status |
Architecture
MCP Client (Claude / Cursor / etc.)
│ MCP Protocol (stdio)
▼
userology-mcp-server
│ HTTPS
▼
researcher-service (existing Userology backend)License
MIT
Available Tools
42 toolscopy_studyA
Duplicate an existing study and all its sections.
Creates a new study with the same objectives, persona, sections, and interview guides. The copy starts in Draft status with no participant sessions. Useful for iterating on a study template without modifying the original.
Args: study_id: The unique identifier of the study to copy.
Inputs: study_id (required). Returns: result
create_sectionA
Add a new section to a study.
REQUIRED NEXT STEPS after calling this — do not skip:
Call update_section to set the section's name and description.
Call generate_guide to create the AI interview guide.
Present the generated guide to the user for review.
SECTION TYPES:
"prototype": Testing interactive Figma prototypes
"conceptTesting": Feedback on mockups or early-stage concepts
"voiceInterview": Open-ended discussion, no visual stimulus
"liveProductResearch": Testing against a live product URL
Returns: New section object with id, type, and index.
Args: study_id: The unique identifier of the study. section_type: One of 'prototype', 'conceptTesting', 'voiceInterview', 'liveProductResearch'. index: Zero-based position for the new section (default: 0).
Inputs: study_id (required), section_type (required), index. Returns: result
create_studyA
Create a new UX research study using AI-powered generation.
⏱️ IMPORTANT: This takes 30-90 seconds. Tell the user it will take about a minute and ask them to wait while the AI generates the study.
This is the PRIMARY way to create studies. The AI will automatically:
Generate a study name from the description
Define research objectives
Identify the target user persona
Create appropriate sections (voice interview, prototype testing, etc.)
Generate interview guides for each section
After creation, ALWAYS present the study summary to the user showing what was generated (name, objectives, persona, sections).
For best results, the description should include:
The product or feature being tested
The target user persona (e.g., "B2B SaaS power users", "first-time mobile shoppers")
The research goals (usability, satisfaction, discovery, etc.)
Any specific tasks or flows to test
Prototype or Figma URLs if testing a design
Args: description: Natural language description of the research study to create. Include details about what you want to research, the product, target users, and any specific methodologies needed.
Inputs: description (required). Returns: result
create_synthesis_chatA
Start a new Synthesis Studio AI analysis chat for a study.
Synthesis Studio lets you have an AI-powered conversation to explore research findings, ask follow-up questions, and generate new insights.
Best used after the study has collected participant sessions — the AI analyzes the actual session data to answer questions. Analytics do not need to be pre-generated; Synthesis Studio works directly from session data.
After creating, use send_synthesis_message to ask questions.
Args: study_id: The unique identifier of the study to analyze. title: Optional title for the chat session.
Inputs: study_id (required), title. Returns: result
delete_sectionA
DESTRUCTIVE: Permanently remove a section from a study.
This deletes the section, its interview guide, and all associated configuration. This cannot be undone.
Do NOT call this tool in the same turn as the deletion request. First respond with: "Are you sure you want to delete section '[name]'? This cannot be undone." Only call this tool after the user confirms in a follow-up message.
Args: study_id: The unique identifier of the study. section_id: The unique identifier of the section/task to delete.
Inputs: study_id (required), section_id (required). Returns: result
delete_studyA
DESTRUCTIVE: Permanently delete a study and ALL its associated data.
This cannot be undone. It deletes all participant sessions, recordings, transcripts, analytics, and interview guides for this study.
Do NOT call this tool in the same turn as the deletion request. First respond with: "Are you sure you want to permanently delete '[study name]' and all its data? This cannot be undone." Only call this tool after the user confirms in a follow-up message.
Args: study_id: The unique identifier of the study to delete.
Inputs: study_id (required). Returns: result
delete_synthesis_chatA
DESTRUCTIVE: Delete a Synthesis Studio chat and its entire message history.
Do NOT call this tool in the same turn as the deletion request. First respond with: "Are you sure you want to delete this analysis chat? The full conversation history will be permanently lost." Only call this tool after the user confirms in a follow-up message.
Args: chat_id: The unique identifier of the chat to delete.
Inputs: chat_id (required). Returns: result
generate_analyticsA
Trigger AI-powered analytics generation for a study.
⚠️ PREREQUISITE: The study must have at least one completed participant session. Call get_participants first — if no sessions are completed, analytics cannot be generated. Also call get_analytics_status first to avoid redundant generation.
⏱️ This takes 2-5 minutes depending on the number of sessions. Inform the user this will take several minutes.
This generates all analytics components: qualitative insights, quantitative data, Q&A analysis, summary, and overall insights.
This call returns immediately — generation runs in the background. After calling this, poll get_analytics_status to monitor progress:
Call get_analytics_status up to 10 times to check for completion.
If still not complete after 10 checks, tell the user: "Analytics generation is still in progress. Please ask me to check again in a few minutes."
Once complete, call the appropriate read tools for what the user needs.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
generate_guideA
Generate an AI-powered interview guide for a section using the study's objectives, target persona, and section configuration.
⚠️ PREREQUISITES: The study must have objectives and persona set, and the section must have a name and description. Call update_study_details and update_section first if these are not yet configured.
⏱️ This takes 30–90 seconds. Warn the user before calling.
After generation, present the guide to the user for review. If they request changes, use update_interview_guide — do NOT regenerate from scratch.
Returns: The full guide content in markdown format.
Args: study_id: The unique identifier of the study. section_id: The unique identifier of the section.
Inputs: study_id (required), section_id (required). Returns: result
generate_study_reportA
Trigger generation of the comprehensive study report.
⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if analytics are missing, call generate_analytics and wait for completion before calling this.
⏱️ This takes 3-5 minutes. Inform the user this will take several minutes.
This call returns immediately — report generation runs in the background. After calling this, poll get_analytics_status to check the report component:
Call get_analytics_status up to 10 times to check for completion.
If still not complete after 10 checks, tell the user: "Report generation is still in progress. Please ask me to check again in a few minutes."
Once the report component shows as complete, call get_study_report.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_analytics_statusA
Check what analytics have been generated for a study.
Returns the status of each analytics component (qual, quant, QnA, summary, insights, report). Use the result to decide next steps:
If all needed components are present: call the read tools directly.
If analytics are missing or stale: call generate_analytics first (takes 2-5 min), then call the read tools once generation is complete.
Always call this before generate_analytics to avoid re-generating unnecessarily.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_analytics_summaryA
Get a short, concise AI-generated text summary of the study's overall findings.
Use this first when a user asks for a quick overview of study results. If they want to go deeper, follow up with the appropriate tool:
get_qualitative_insights: themes and patterns (the "why")
get_quantitative_data: metrics and completion rates (the "how many")
get_qna_analysis: per-participant Q&A breakdown (individual responses)
get_study_insights: actionable recommendations (what to fix)
⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.
Returns: Short summary text (typically 200–400 words) of key findings.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_figma_contextA
Analyze a Figma prototype and extract screen context for UX research.
This fetches the Figma file, extracts screen information, and returns structured data about the prototype's pages and frames.
Args: user_id: The Userology user ID of the person requesting Figma access. This is the account owner's UID — if unknown, ask the user to provide it or check their Userology profile settings. Note: this is NOT the study_id. figma_link: The Figma file URL to analyze.
Inputs: user_id (required), figma_link (required). Returns: result
get_interview_guidesA
Get all interview guides for every section in a study.
Returns the full guide content (markdown) for each section that has one. Use this after study creation to see the AI-generated interview guides.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_participantsA
List all participants in a study, including their session status and metadata.
Call this first whenever you need participant_id or session_id values. These IDs are required by get_session, get_session_report, get_session_recordings, and get_participant_sessions_report.
Returns each participant's ID, name (if available), session IDs, and completion status (e.g., completed, in-progress, invited).
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_participant_sessions_reportA
Get an aggregated report for all sessions completed by a specific participant.
Use when the user wants to understand one person's overall experience or performance across multiple sessions in the same study.
For reports across ALL participants, use get_sessions_report. For a single specific session, use get_session_report.
⚠️ PREREQUISITE: Analytics should be generated first for best results (use generate_analytics + poll get_analytics_status until complete). Call get_participants first to find the correct participant_id.
Args: study_id: The unique identifier of the study. participant_id: The unique identifier of the participant.
Inputs: study_id (required), participant_id (required). Returns: result
get_qna_analysisA
Get per-participant Q&A analysis — each participant's responses organized by subtopic across all study sections.
Use this when the user wants to compare how different participants answered the same questions, or to see individual-level responses side by side.
⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_qualitative_insightsA
Get qualitative analysis for a study — themes, patterns, and insights.
Use this when the user wants to understand the "why" behind participant behavior: recurring themes, usability friction points, and positive findings across sessions.
⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.
Includes overview, positive findings, and challenges discovered across participant sessions.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_quantitative_dataA
Get quantitative metrics for a study — task completion rates, times, misclicks, and other measurable data.
Use this when the user wants numbers: "how many people completed the task", "what was the average time", or "where did people click most". Most relevant for prototype and conceptTesting sections that capture interaction data.
⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_sectionA
Get full details of a specific section including its configuration and settings.
Call get_sections first if you need to find the section_id.
Args: study_id: The unique identifier of the study. section_id: The unique identifier of the section/task.
Inputs: study_id (required), section_id (required). Returns: result
get_sectionsA
List all sections (tasks) in a study with their types, names, and IDs.
Use this to find section_id values needed for get_section, update_section, delete_section, generate_guide, and update_interview_guide.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_sessionA
Get raw transcript and interaction events for a single participant session.
Use this when the user wants to read what a participant actually said verbatim, or review the full unprocessed interaction log.
For an AI-analyzed summary with themes, key quotes, and task performance assessment, use get_session_report instead.
Call get_participants first to find the correct participant_id and session_id.
Args: study_id: The unique identifier of the study. participant_id: The unique identifier of the participant. session_id: The unique identifier of the session.
Inputs: study_id (required), session_id (required), participant_id (required). Returns: result
get_session_recordingsA
Get recording URLs (video/audio) for a specific session.
Returns video and/or audio stream/download links for the session recording. Call get_participants first to find the correct participant_id and session_id.
Args: study_id: The unique identifier of the study. participant_id: The unique identifier of the participant. session_id: The unique identifier of the session.
Inputs: study_id (required), session_id (required), participant_id (required). Returns: result
get_session_reportA
Get the AI analysis report for a single participant's session.
Use this when investigating one specific participant's performance, responses, or behavior in detail.
⚠️ PREREQUISITE: Analytics must be generated first (use generate_analytics + poll get_analytics_status until complete). Call get_participants first to get the correct participant_id and session_id.
Returns: Session report with transcript highlights, task performance, key quotes, and AI-generated observations for this participant.
Args: study_id: The unique identifier of the study. participant_id: The unique identifier of the participant. session_id: The unique identifier of the session.
Inputs: study_id (required), session_id (required), participant_id (required). Returns: result
get_sessions_reportA
Get an aggregated analysis report across ALL sessions in a study.
Use this for study-level synthesis: overall patterns, common findings, aggregate completion rates.
For a single participant's session, use get_session_report(study_id, participant_id, session_id). For all sessions by one participant, use get_participant_sessions_report(study_id, participant_id).
Returns: Aggregated report object with overall findings, patterns, and per-section summaries across all participants.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_studyA
Fetch the full configuration of a study including all sections, status, objectives, persona, product overview, and metadata.
Use this when you need raw study data for programmatic processing or to check specific field values.
For a human-readable overview to present to the user, prefer get_study_summary.
Returns: Full study object with fields: id, name, status, objective, user_details, product_overview, sections (list of section objects).
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_study_insightsA
Get overall and per-section insights for a study, including key findings and actionable recommendations.
Use this when the user asks "what should we fix", "what are the main issues", or wants prioritized action items broken down by study section.
For a shorter executive summary, use get_analytics_summary instead. For the full combined report, call generate_study_report then get_study_report.
⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_study_reportA
Retrieve the full comprehensive study report combining all analytics.
This report must be generated first using generate_study_report. Call get_analytics_status to verify the report component exists before fetching.
If this returns empty or a "not found" response, the report has not been generated yet. Recovery path:
Call get_analytics_status — if analytics components are missing, call generate_analytics first and wait for completion.
Then call generate_study_report (takes 3-5 min), polling get_analytics_status until the report component shows complete.
Then call this tool again to retrieve the result.
Returns: Complete report document in markdown/structured format covering qualitative insights, quantitative data, Q&A analysis, and recommendations.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_study_summaryA
Get a formatted, human-readable summary of a study.
Use this to present study details to the user after creation or modification. Do NOT use this for programmatic field access — use get_study instead.
Returns: Formatted text showing study name, status, objectives, target persona, and a list of all sections with their types and names.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_study_tagsB
Get all tags assigned to a study, useful for organizing and filtering studies.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
get_synthesis_chatA
Get a specific Synthesis Studio chat with its full message history.
Use this to review a previous conversation, show the user what questions have already been asked, or pick up where an analysis session left off.
Args: chat_id: The unique identifier of the chat.
Inputs: chat_id (required). Returns: result
get_ui_annotationsA
Get UI annotation data (heatmaps, click data) for a study.
Most relevant for studies with prototype or conceptTesting sections — these capture click interactions that appear as heatmaps and misclick data. For voice interview sections, this data may be sparse or empty.
⚠️ PREREQUISITE: Analytics must be generated first. Call get_analytics_status — if components are missing, call generate_analytics and wait for completion.
Args: study_id: The unique identifier of the study.
Inputs: study_id (required). Returns: result
list_studiesA
List all studies for the current tenant/organization.
Start here when no study_id is provided. Returns IDs, names, and statuses for all studies. After listing, ask the user which study they'd like to work with, then call get_study_summary for a human-readable overview or get_study for the full raw config.
Inputs: no named parameters. Returns: result
list_synthesis_chatsA
List all Synthesis Studio AI chats across all studies.
Returns chat IDs, titles, and associated study IDs. Use this to find existing chats to resume with get_synthesis_chat, or to show the user their analysis history before creating a new one.
Inputs: no named parameters. Returns: result
send_synthesis_messageA
Send a message to a Synthesis Studio AI chat and receive an analysis response.
Use this to ask questions about research data, explore themes, request comparisons across participants, or generate new insights from the data.
⏱️ Responses take 30–90 seconds depending on query complexity. Warn the user.
Returns: AI analyst's response text with findings, patterns, or answers based on the study's session data.
Args: chat_id: The unique identifier of the chat (from create_synthesis_chat). message: The question or request to send to the AI analyst.
Inputs: chat_id (required), message (required). Returns: result
update_interview_guideA
Replace the interview guide content for a specific section.
Users should FIRST generate a guide using generate_guide, then edit it using this tool if changes are needed. Do NOT write guides from scratch.
Args: study_id: The unique identifier of the study. section_id: The unique identifier of the section/task. guide_content: The full guide content in markdown format.
Inputs: study_id (required), section_id (required), guide_content (required). Returns: result
update_sectionA
Update a section's name, description, prototype link, or Figma link.
Args: study_id: The unique identifier of the study. section_id: The unique identifier of the section/task. name: New name for the section. description: New description for the section. prototype_link: URL of the prototype associated with this section. figma_link: Figma file URL for the section.
Inputs: study_id (required), section_id (required), name, figma_link, +2 more. Returns: result
update_study_detailsB
Update study details such as objective, user details, and product overview.
Args: study_id: The unique identifier of the study. objective: The research objective or goal. user_details: Description of the target user/persona. product_overview: Overview of the product being researched.
Inputs: study_id (required), objective, user_details, product_overview. Returns: result
update_study_nameA
Rename a study.
Args: study_id: The unique identifier of the study. name: The new name for the study.
Inputs: name (required), study_id (required). Returns: result
update_study_statusB
Change the status of a study.
Args: study_id: The unique identifier of the study. status: New status — one of 'Draft', 'Active', 'Paused', 'Completed'.
Inputs: status (required), study_id (required). Returns: result
update_study_tagsA
Update the tags for a study. Provide tags as a comma-separated string.
Args: study_id: The unique identifier of the study. tags: Comma-separated list of tags (e.g., "usability,checkout,mobile").
Inputs: tags (required), study_id (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 42 tools
Most tools have clearly distinct purposes, with descriptions carefully differentiating between similar get_* analytics tools (e.g., get_analytics_summary vs get_study_insights vs get_sessions_report). The get_study vs get_study_summary pair is explicitly disambiguated, and report tools are scoped by participant/session/study. Only minor overlap exists among the various analytics read tools, but the guidance is strong.
The server follows a consistent get_*/create_*/update_*/delete_*/generate_* pattern, making most tool names predictable. Minor inconsistencies exist: list_studies vs get_sections/get_participants, and copy_study uses a verb not aligned with the standard create/update/delete set. Overall, the naming is coherent and readable.
With 42 tools, this server exceeds the 'too many' threshold of 25+ for the apparent scope. While the domain (UX research) is broad, many specialized analytics read tools (e.g., get_qualitative_insights, get_quantitative_data, get_qna_analysis) could potentially be consolidated. The high count will likely overwhelm agents and increase selection difficulty.
The tool set is very comprehensive: full study CRUD, sections with guide generation/editing, participant and session retrieval, analytics generation and multiple read views, report generation, synthesis chat, tags, and Figma integration. Minor gaps exist (e.g., no section reordering, no participant CRUD), but core workflows have no dead ends and dependencies are clearly documented.
Maintenance
Related MCP Connectors
Run user research from any AI tool. Create studies, recruit participants, query insights.
Create, launch, and analyze user research studies, AI interviews, and AI tests from your AI agent.
Run UX research from Claude — create card sort studies, list studies, pull headline stats.
AI-moderated research platform: create and launch studies and query interview results.
Related MCP Servers
- AlicenseCqualityBmaintenanceRun real user interviews from AI agents and retrieve structured insights with themes and verbatim quotes.55MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with JetBrains YouTrack for issue, project, and user management through natural language.1-
- FlicenseNot gradedqualityCmaintenanceEnables AI tools to interact with the Fellow.ai API for managing action items, notes, recordings, webhooks, and user info with full CRUD operations.1-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to conduct user research workflows directly from Great Question, including creating studies, recruiting participants, and querying insights.MIT