playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

DollhouseMCP MCP server

Enables dynamic persona management from markdown files with local creation, GitHub marketplace integration, and behavioral switching capabilities for role-playing and domain-specific customization.
Back to servers
Setup instructions
Provider
Mick Darling
Release date
Jul 02, 2025
Language
TypeScript
Stats
1 star
View on GitHub

DollhouseMCP is a comprehensive Model Context Protocol (MCP) server that enables dynamic AI persona management with a GitHub-powered marketplace. It allows Claude and other compatible AI assistants to activate different behavioral personas while supporting community sharing.

Installation

NPM Installation (Recommended)

npm install -g @mickdarling/dollhousemcp

Alternative: Manual Installation

# Clone the repository
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server

# Install dependencies and build
npm install
npm run build

# Optional: Set user identity for persona attribution
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="[email protected]"

Configuration

Claude Desktop Configuration

Add DollhouseMCP to your Claude Desktop configuration:

For NPM Installation:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "npx",
      "args": ["@mickdarling/dollhousemcp"]
    }
  }
}

For Source Installation:

{
  "mcpServers": {
    "dollhousemcp": {
      "command": "node",
      "args": ["/absolute/path/to/DollhouseMCP/dist/index.js"]
    }
  }
}

Configuration locations:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

After configuration, restart Claude Desktop completely.

Available Tools

Core Persona Management

  • list_personas - Display all local personas with enhanced metadata
  • activate_persona - Activate by name, filename, or unique ID
  • get_active_persona - Get current persona information
  • deactivate_persona - Return to default mode
  • get_persona_details - View complete persona details
  • reload_personas - Refresh from filesystem

GitHub Marketplace Integration

  • browse_marketplace - Browse personas by category
  • search_marketplace - Search across all marketplace personas
  • get_marketplace_persona - View detailed marketplace persona info
  • install_persona - One-click download and installation
  • submit_persona - Submit to marketplace via GitHub issue

User Identity Management

  • set_user_identity - Set username for persona attribution
  • get_user_identity - View current identity status
  • clear_user_identity - Return to anonymous mode

Chat-Based Persona Management

  • create_persona - Guided persona creation through chat
  • edit_persona - Modify existing persona fields
  • validate_persona - Comprehensive quality validation

Auto-Update System

  • check_for_updates - Check GitHub releases for available updates
  • update_server - Automated git pull + npm install + build with backup
  • rollback_update - Restore previous version from automatic backups
  • get_server_status - Get server status with version and system details

Persona Indicators

  • configure_indicator - Configure how persona indicators appear in responses
  • get_indicator_config - View current indicator configuration settings

Usage Examples

Marketplace Operations

browse_marketplace                           # See all categories
browse_marketplace "creative"                # Browse creative personas
search_marketplace "writing"                 # Search for writing personas
install_persona "creative/storyteller.md"    # Install from marketplace

Persona Creation & Management

create_persona "Study Buddy" "A helpful tutor" "educational" "You are a patient tutor..."
edit_persona "Study Buddy" "description" "An encouraging academic mentor"
validate_persona "Study Buddy"               # Check quality and format
submit_persona "Study Buddy"                 # Share with community

User Identity

set_user_identity "your-username"            # Set attribution
get_user_identity                            # Check current status
clear_user_identity                          # Return to anonymous

Auto-Update Operations

check_for_updates                            # Check for new versions
get_server_status                            # View current version and system info
update_server true                           # Perform automated update with backup
rollback_update true                         # Revert to previous version if needed

Persona Indicators

get_indicator_config                         # View current settings
configure_indicator enabled:false            # Disable indicators
configure_indicator style:"minimal"          # Use minimal format: 🎭 Creative Writer
configure_indicator style:"compact"          # Use compact: [Creative Writer v2.1]
configure_indicator style:"full"             # Full format (default)

Docker Installation

Quick Start with Docker

# Clone repository
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server

# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t dollhousemcp .
docker run -d --name dollhousemcp dollhousemcp

Custom Personas with Docker

# Mount your custom personas directory
docker run -d \
  --name dollhousemcp \
  -v /path/to/your/personas:/app/personas \
  -e DOLLHOUSE_USER="your-username" \
  dollhousemcp

Creating Custom Personas

Create .md files in the personas/ directory with this structure:

---
name: "Your Persona Name"
description: "Brief description of what this persona does"
unique_id: "auto-generated-if-missing"
author: "your-username"
triggers: ["keyword1", "keyword2"]
version: "1.0"
category: "creative"
age_rating: "all"
ai_generated: false
generation_method: "human"
price: "free"
license: "CC-BY-SA-4.0"
---

# Your Persona Name

Your persona instructions go here. This content defines how the AI should behave when this persona is activated.

## Response Style
- Communication guidelines
- Tone and approach
- Specific behaviors

## Key Techniques
- Problem-solving methods
- Interaction patterns

Troubleshooting

Common Issues

Issue Solution
Personas not loading Check personas/ directory exists and has read permissions
Server won't start Run npm run rebuild to clean and rebuild
Marketplace not working Check internet connection and GitHub API access
User identity not saving Set DOLLHOUSE_USER environment variable before starting Claude
"Cannot find module" errors Ensure npm install completed successfully
TypeScript compilation errors Verify Node.js version is 20+ with node --version
Tools not appearing in Claude Restart Claude Desktop completely after config changes
Default personas modified v1.2.1+ uses copy-on-write; git restore if needed
Update/rollback issues Check write permissions; disable with DOLLHOUSE_DISABLE_UPDATES=true

Debug Steps

  1. Check build status:

    npm run build

  2. Verify persona files:

    ls -la personas/*.md

  3. Test server startup:

    node dist/index.js

  4. Validate configuration:

    # Check Claude Desktop config
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Verify Node.js version (requires 20+)
node --version

  5. Test auto-update system:

    # Use within Claude Desktop
check_for_updates    # Check for available updates
get_server_status    # View system information

  6. Validate personas: Use the reload_personas tool to check for loading errors

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "dollhousemcp" '{"command":"node","args":["/absolute/path/to/DollhouseMCP/dist/index.js"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "dollhousemcp": {
            "command": "node",
            "args": [
                "/absolute/path/to/DollhouseMCP/dist/index.js"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "dollhousemcp": {
            "command": "node",
            "args": [
                "/absolute/path/to/DollhouseMCP/dist/index.js"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later