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., "@usuarios Crear perfiles sintéticos de las entrevistas"
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.
Create research-backed user profiles that validate your designs across every sprint.
usuarios is an MCP server that turns your service design research (interviews, observations, field notes) into synthetic user profiles — rich, 12-dimension archetypes you can use to validate designs, align teams, and test ideas. All through natural conversation in Claude Desktop or Codex Desktop.
They say | The AI does |
"Creá usuarios sintéticos de las entrevistas" | Analyzes your research, extracts patterns, generates full profiles |
"Validá el onboarding contra María" | Tests your design against María's criteria, returns a report |
"¿Cómo va el proyecto?" | Shows a dashboard with research → patterns → profiles → validations |
"Refiná el perfil de Juan" | Updates the profile with new insights, versions it |
Zero technical knowledge needed. Your team just chats.
Related MCP server: mcp-usercall
uv# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"usuarios": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Sebtiago/usuarios-mcp",
"usuarios-mcp"
]
}
}
}Codex Desktop: Edit ~/.codex/config.toml:
[mcp_servers.usuarios]
command = "uvx"
args = [
"--from",
"git+https://github.com/Sebtiago/usuarios-mcp",
"usuarios-mcp"
]"Inicializá usuarios para este proyecto"
That's it. The server handles everything else.
Based on This Is Service Design Doing, Mapping Experiences, and the Touchpoint Journal:
Dimension | What it captures |
1. Identity | Name, archetype, real quotes from research |
2. Empathy Map | Sees, hears, thinks/feels, says/does |
3. Jobs-to-be-Done | When/I want/So I can (functional, emotional, social) |
4. Pain Points | Intensity, frequency, context, traceability |
5. Behaviors | Patterns, triggers, workarounds |
6. Mindset | Beliefs, tech literacy, change attitude |
7. Ecosystem | Current tools, key people in their network |
8. Scenarios | Real usage flows with emotional arcs |
9. Emotional Journey | Stage-by-stage emotion map |
10. Validation Criteria | Intent principles + testable questions |
11. Traceability | Direct/Inferred/Speculative %, all sources cited |
12. Metadata | Version, expiration (12 months), human validation |
Every profile is saved in both JSON (machine-readable) and Markdown (team-readable).
INVESTIGACIÓN → ANÁLISIS → PERFILES → VALIDACIÓN → EVOLUCIÓN
(research/) (patterns/) (profiles/) (validations/) (versioned)The AI host orchestrates everything automatically. You never touch the tools directly.
After initialization, your project looks like this:
your-project/
└── .usuarios/
├── config.yaml # Project settings
├── research/ # Drop your interview files here (.md, .txt)
│ ├── entrevista-1.md
│ └── focus-group.md
├── patterns/ # Extracted patterns (auto-generated)
│ ├── patterns.json
│ └── patterns.md
├── profiles/ # Your synthetic users (auto-generated)
│ ├── maria-cuidadora.json
│ └── maria-cuidadora.md
└── validations/ # Design validation reports
└── 2026-06-22-onboarding.md# Clone
git clone https://github.com/Sebtiago/usuarios-mcp.git
cd usuarios-mcp
# Install dependencies
uv sync
# Run locally
uv run python main.py
# Customize templates (optional)
# Create .usuarios/templates/analyze.md in your project
# to override the default analysis methodologyRuns locally. No cloud, no API keys, no data leaves your machine.
Does not call LLM APIs. The AI host (Claude/GPT) processes everything with its existing model.
Your research data stays in .usuarios/ in your project folder.
This tool implements the service design methodology from:
This Is Service Design Doing — Stickdorn, Hormess, et al.
Good Services — Louise Downe
Mapping Experiences — Jim Kalbach
Touchpoint: The Journal of Service Design
Analysis-Synthesis Bridge Model for AI in design
MIT © Santiago Sirias
Built for designers, by a designer. If this helps your team, ⭐ the repo.
Generate a prompt for creating synthetic user profiles.
Reads the patterns file and returns a prompt with the complete 12-dimension profile schema for you to generate rich synthetic user profiles.
Args: project_path: Absolute path to the project directory. count: Optional number of profiles to generate (default: auto-detect from patterns).
Inputs: project_path (required), count. Returns: result
Get a specific profile by ID.
Args: project_path: Absolute path to the project directory. profile_id: The profile identifier (e.g. "maria-cuidadora"). format: Output format: "json" (structured) or "markdown" (human-readable).
Inputs: project_path (required), profile_id (required), format. Returns: result
Get the current project configuration.
Args: project_path: Absolute path to the project directory.
Inputs: project_path (required). Returns: result
Generate an analysis prompt from research data.
Reads all research files (or specified subset) and returns a prompt that you (the AI host) should process with your LLM to extract:
Behavioral patterns
Pain points
Goals and motivations
Environment/context factors
Key differentiators between user segments
After processing, call save_patterns with the structured result.
Args: project_path: Absolute path to the project directory. source_files: Optional list of specific file names to analyze.
Inputs: project_path (required), source_files. Returns: result
Generate a validation prompt for testing a design against a profile.
Reads the specified profile and design document, then returns a prompt for you to evaluate the design against the user's criteria and needs.
Args: project_path: Absolute path to the project directory. profile_id: The profile to validate against (e.g. "maria-cuidadora"). design_file: Path to the design document to validate (relative to project).
Inputs: project_path (required), profile_id (required), design_file (required). Returns: result
Get the complete workflow guide for using usuarios-mcp.
Returns detailed instructions on how to use the server effectively: autonomous workflows, methodology, and UX principles.
Call this when you need a refresher on the correct workflow.
Inputs: no named parameters. Returns: result
Initialize a new usuarios project.
Creates the .usuarios/ directory structure: .usuarios/ config.yaml research/ <- Put interview files here patterns/ <- Analysis results go here profiles/ <- Generated profiles (JSON + MD) validations/ <- Validation reports
Args: project_path: Absolute path to the project directory.
Inputs: project_path (required). Returns: result
List all synthetic user profiles in the project.
Args: project_path: Absolute path to the project directory.
Inputs: project_path (required). Returns: result
List all research files in the project.
Args: project_path: Absolute path to the project directory.
Inputs: project_path (required). Returns: result
List all validation reports in the project.
Args: project_path: Absolute path to the project directory.
Inputs: project_path (required). Returns: result
Get a dashboard overview of the entire project.
Shows research files count, patterns status, profiles created, validations run, and project health. Call this FIRST in any workflow to understand the current state.
Args: project_path: Absolute path to the project directory.
Inputs: project_path (required). Returns: result
Save extracted research patterns to the project.
Accepts the patterns as a JSON string. The patterns should follow the structure provided by the get_research_prompt output.
Args: project_path: Absolute path to the project directory. patterns: JSON string with the analysis results.
Inputs: project_path (required), patterns (required). Returns: result
Save a generated synthetic user profile.
Saves both a JSON file (for machine consumption) and a Markdown file (for human consumption). The profile must follow the 12-dimension schema provided by get_generate_prompt.
Args: project_path: Absolute path to the project directory. profile: JSON string with the 12-dimension profile.
Inputs: project_path (required), profile (required). Returns: result
Save a validation report.
Args: project_path: Absolute path to the project directory. profile_id: The profile that was validated against. report: JSON string with the validation report.
Inputs: project_path (required), profile_id (required), report (required). Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 14 tools
Each tool has a clear, distinct purpose. Tools like get_generate_prompt, get_research_prompt, and get_validate_prompt serve different stages of the workflow, while list_ and save_ tools operate on different resources. There is no overlap or confusion.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_profile, save_patterns, list_research). The verbs (get, init, list, save, quick) are appropriate for the action, and the naming makes the tool's purpose immediately clear.
With 14 tools, the server is well-scoped for its domain of user research and synthetic profile generation. Each tool contributes to a specific step in the workflow without redundancy or unnecessary bloat.
The tool set covers the full research-to-validation workflow: initialization, research analysis, pattern extraction, profile generation, and validation. Missing are update/delete operations for resources, but the forward-only generation process mostly mitigates this need.
Deploy AI user personas to validate user journeys at scale. Find UX friction before real users do.
Generate synthetic random user data for testing, demos, and development without using real persona.
AI-moderated research interviews: design, run and analyze interview studies with real participants
AI-moderated voice interviews with your customers, delivering themes and insights
