🚀 DollhouseMCP
DollhouseMCP is a comprehensive Model Context Protocol (MCP) server that enables dynamic AI persona management. It allows Claude and other compatible AI assistants to activate different behavioral personas, supporting community sharing and monetization.

🚀 Quick Start
Installation
NPM Installation (NEW! - Recommended)
npm install -g @mickdarling/dollhousemcp
{
"mcpServers": {
"dollhousemcp": {
"command": "npx",
"args": ["@mickdarling/dollhousemcp"]
}
}
}
Restart Claude Desktop and you're ready to use DollhouseMCP! Try list_personas to get started.
Automated Setup (Alternative) - Claude Desktop Only
[!WARNING]
Claude Desktop Only: The automated setup script is specifically designed for Claude Desktop integration. If you're using Claude Code, other AI platforms (ChatGPT, BoltAI, Gemini, etc.), or custom MCP implementations, please use the Manual Installation process below.
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
./setup.sh
The setup script will:
- 📦 Install all dependencies
- 🔨 Build the TypeScript code
- 📍 Detect your installation path
- 🔧 Generate the exact Claude Desktop configuration
- 📋 Provide step-by-step setup instructions
Manual Installation
Note: Manual installation works with all MCP-compatible platforms including Claude Desktop, Claude Code, ChatGPT, BoltAI, Gemini, and custom implementations.
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install
npm run build
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="your-email@example.com"
Claude Desktop Configuration
Add DollhouseMCP to your Claude Desktop configuration:
Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
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"]
}
}
}
🔄 After configuration:
- Save the file
- Restart Claude Desktop completely
- All 23 DollhouseMCP tools will be available
✨ Features
| Feature |
Description |
| 🎭 23 MCP Tools |
Complete persona lifecycle management through chat interface |
| 🏪 GitHub Collection |
Browse, search, install, and submit personas to community collection |
| 👤 User Identity System |
Environment-based attribution for persona creators |
| 🆔 Unique ID System |
Advanced ID generation: what-it-is_YYYYMMDD-HHMMSS_who-made-it |
| 💬 Chat-Based Management |
Create, edit, and validate personas through conversational interface |
| 🔄 Real-time Operations |
Live editing with automatic version bumping and validation |
| 🚀 Auto-Update System |
Enterprise-grade auto-update with backup/rollback and dependency validation |
| 🛡️ Data Protection |
Copy-on-write for default personas, comprehensive backup system |
| 🏠 Local-First Architecture |
Full functionality without cloud dependency |
📦 Installation
Prerequisites
- Node.js: v20.0.0 or higher (LTS recommended)
- npm: v10.0.0 or higher
- git: For cloning the repository
- Operating System: Windows, macOS, or Linux
Note: DollhouseMCP is developed on Node.js 24 but supports Node.js 20+ for broad compatibility.
Cross-Platform Installation
🐧 Linux Installation
sudo apt update
sudo apt install -y nodejs npm git
node --version
sudo dnf install -y nodejs npm git
node --version
sudo pacman -S nodejs npm git
node --version
Note: If your system's Node.js is older than v20, install from NodeSource or use nvm.
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install
npm run build
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="your-email@example.com"
~/.config/Claude/claude_desktop_config.json
$XDG_CONFIG_HOME/Claude/claude_desktop_config.json
{
"mcpServers": {
"dollhousemcp": {
"command": "node",
"args": ["/absolute/path/to/DollhouseMCP/dist/index.js"]
}
}
}
🪟 Windows Installation
choco install nodejs --version=20.18.0
choco install git
winget install OpenJS.NodeJS Git.Git
node --version
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install
npm run build
$env:DOLLHOUSE_USER = "your-username"
$env:DOLLHOUSE_EMAIL = "your-email@example.com"
$env:APPDATA\Claude\claude_desktop_config.json
{
"mcpServers": {
"dollhousemcp": {
"command": "node",
"args": ["C:/path/to/DollhouseMCP/dist/index.js"]
}
}
}
🍎 macOS Installation
brew install node git
node --version
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
npm install
npm run build
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="your-email@example.com"
~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"dollhousemcp": {
"command": "node",
"args": ["/absolute/path/to/DollhouseMCP/dist/index.js"]
}
}
}
🐳 Docker Installation
git clone https://github.com/DollhouseMCP/mcp-server.git
cd mcp-server
docker-compose up -d
docker build -t dollhousemcp .
docker run -d --name dollhousemcp dollhousemcp
Docker Compose (Recommended)
docker-compose up -d
docker-compose --profile dev up dollhousemcp-dev
docker run -d \
--name dollhousemcp \
-v /path/to/your/personas:/app/personas \
-e DOLLHOUSE_USER="your-username" \
dollhousemcp
DOLLHOUSE_USER=your-username
DOLLHOUSE_EMAIL=your-email@example.com
PERSONAS_DIR=/app/personas
NODE_ENV=production
💻 Usage Examples
Collection Operations
browse_collection # See all categories
browse_collection "creative" # Browse creative personas
search_collection "writing" # Search for writing personas
install_persona "creative/storyteller.md" # Install from collection
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 System
check_for_updates # Check GitHub releases for available DollhouseMCP updates
get_server_status # Comprehensive server status with version, git info, and system details
update_server true # Automated git pull + npm install + build with backup creation
rollback_update true # Restore previous version from automatic backups
How Auto-Update Works:
- Version Check: Queries GitHub releases API for latest version
- Backup Creation: Automatically backs up current installation (including user personas)
- Update Process:
- Performs
git pull to fetch latest code
- Runs
npm install for dependency updates
- Rebuilds TypeScript with
npm run build
- Verification: Validates the update succeeded
- Rollback Option: Keep last 5 backups for easy recovery
Safety Features:
- Rate limiting prevents API abuse
- GPG signature verification (when available)
- Dependency version validation
- Automatic backup retention (5 most recent)
- User personas preserved during updates
Persona Indicators
DollhouseMCP adds visual indicators to AI responses when a persona is active:
[🎭 Creative Writer v2.1 by @mickdarling] Your creative response here...
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)
configure_indicator emoji:"🤖" # Change emoji
configure_indicator showAuthor:false # Hide author attribution
configure_indicator bracketStyle:"round" # Use (parentheses) instead of [brackets]
export DOLLHOUSE_INDICATOR_ENABLED=true
export DOLLHOUSE_INDICATOR_STYLE=minimal
export DOLLHOUSE_INDICATOR_EMOJI=🎨
📚 Documentation
Available Tools (23 Total)
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 Collection Integration
browse_collection - Browse personas by category
search_collection - Search across all collection personas
get_collection_persona - View detailed collection persona info
install_persona - One-click download and installation
submit_persona - Submit to collection 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 DollhouseMCP updates
update_server - Automated git pull + npm install + build with backup creation
rollback_update - Restore previous version from automatic backups
get_server_status - Comprehensive server status with version, git info, and system details
Persona Indicators
configure_indicator - Configure how persona indicators appear in AI responses
get_indicator_config - View current indicator configuration settings
Creating Custom Personas
---
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
| Field |
Description |
name |
Display name for the persona |
description |
Brief description of purpose and capabilities |
| Field |
Description |
unique_id |
Auto-generated in format: what-it-is_YYYYMMDD-HHMMSS_who-made-it |
author |
Creator username (uses DOLLHOUSE_USER environment variable or generates anonymous ID) |
category |
One of: creative, professional, educational, gaming, personal |
triggers |
Array of keywords that suggest when to use this persona |
version |
Semantic version number (auto-incremented on edits) |
age_rating |
Content rating: all, 13+, or 18+ |
ai_generated |
Boolean flag indicating if content was AI-created |
price |
Monetization field - TODO: Future Release (will support "free" or pricing tiers) |
Built-in Personas
| Persona |
Purpose |
Best For |
| Creative Writer |
Imaginative storytelling and creative content |
Brainstorming, creative writing, engaging narratives |
| Technical Analyst |
Deep technical analysis and systematic problem-solving |
Architecture decisions, debugging, technical docs |
| ELI5 Explainer |
Simplifying complex topics for beginners |
Teaching, onboarding, concept explanation |
| Business Consultant |
Strategic business analysis and recommendations |
Strategy planning, business decisions, market analysis |
| Debug Detective |
Systematic debugging and troubleshooting |
Bug hunting, system troubleshooting, root cause analysis |
Collection Integration (Beta)
🧪 Beta Feature: The GitHub-powered collection is currently in beta. Features may change based on community feedback.
- Browse by Category: creative, professional, educational, gaming, personal
- Search Content: Find personas by keywords and descriptions
- One-Click Install: Download and integrate collection personas
- Community Submissions: Submit your personas via
submit_persona tool
- Version Control: Full Git history for all collection content
Note: Collection features require internet connection and GitHub API access. Rate limits may apply.
⚠️ Migration Guide - Breaking Changes
Important: Tool names have changed in recent versions:
browse_marketplace → browse_collection
search_marketplace → search_collection
get_marketplace_persona → get_collection_persona
If you have scripts or workflows using the old tool names, please update them to use the new names.
Business Model & Legal
Licensing
- Core Server: AGPL-3.0 (prevents proprietary competing platforms)
- Persona Content: CC-BY-SA-4.0 for free personas, custom licenses for premium
- Platform Terms: Creator-friendly 80/20 revenue split (applies only to paid personas when monetization is implemented)
Platform Stability Commitments
- 90-day advance notice for monetization changes
- 12-month revenue sharing locks for existing paid personas
- Transparent governance for platform policy updates
- Full data portability rights
- Community advisory input on policy changes
🔧 Technical Details
Project Structure
DollhouseMCP/
├── .github/
│ ├── actions/
│ │ └── validate-yaml/ # Reusable YAML validation action
│ ├── workflows/ # CI/CD workflows
│ └── ISSUE_TEMPLATE/ # Issue templates for bug/feature/task
├── __tests__/
│ ├── unit/ # Unit tests for components
│ ├── integration/ # Integration tests
│ └── *.test.ts # Test files (372 tests total)
├── src/
│ ├── index.ts # Main MCP server (DollhouseMCPServer)
│ ├── cache/ # API caching layer
│ ├── config/ # Configuration management
│ ├── marketplace/ # GitHub collection integration
│ ├── persona/ # Persona management core
│ ├── security/ # Input validation and security
│ ├── server/ # MCP server setup and tools
│ ├── types/ # TypeScript type definitions
│ ├── update/ # Auto-update system components
│ └── utils/ # Utility functions
├── dist/ # Compiled JavaScript (auto-generated)
├── personas/ # Default persona collection
│ ├── creative-writer.md
│ ├── technical-analyst.md
│ ├── eli5-explainer.md
│ ├── business-consultant.md
│ └── debug-detective.md
├── custom-personas/ # User-created personas (git-ignored)
├── docs/ # Documentation
│ ├── auto-update/ # Auto-update system docs
│ └── development/ # Development notes and guides
├── scripts/ # Management and utility scripts
├── Dockerfile # Multi-stage Docker build
├── docker-compose.yml # Production and development configs
├── package.json # Project config (dollhousemcp v1.2.1)
├── tsconfig.json # TypeScript configuration
├── jest.config.cjs # Jest test configuration
├── setup.sh # Automated installation script
├── LICENSE # AGPL-3.0 with platform stability
├── CHANGELOG.md # Version history
├── claude.md # Project context for Claude
└── README.md # This file
Security Features (v1.2.4)
- 🛡️ Content Sanitization: DOMPurify integration prevents XSS attacks in persona content
- 📝 YAML Injection Prevention: Secure parsing with schema validation and size limits
- 🔐 Token Security: GitHub tokens are validated, encrypted at rest, with rotation support
- 🐳 Container Hardening: Non-root execution, read-only filesystem, resource limits
- 🚦 Rate Limiting: Token bucket algorithm prevents API abuse (10 checks/hour default)
- ✅ Signature Verification: GPG verification ensures release authenticity
- 🔍 Input Validation: Comprehensive validation for all user inputs
- 📊 Security Monitoring: Audit logging for security-relevant operations
Testing
npm test
npm run test:coverage
npm run test:watch
npm run test:auto-update
npm run test:personas
npm run test:collection
Test Coverage
- ✅ 102 comprehensive tests covering all functionality
- ✅ Auto-update system - GitHub API, backup/rollback, dependency validation
- ✅ Security testing - Command injection prevention, input validation
- ✅ Cross-platform compatibility - Windows, macOS, Linux path handling
- ✅ Version validation - Parsing tests for git/npm output formats
- ✅ Edge case coverage - Network failures, missing dependencies, malformed input
Manual Verification
npm run build
node dist/index.js --help 2>/dev/null || echo "Server compiled successfully"
ls -la personas/
check_for_updates
get_server_status
Cloud Deployment
The project supports deployment to:
- GitHub Container Registry (ghcr.io)
- Docker Hub
- AWS ECR
- Google Container Registry
AWS ECS
{
"family": "dollhousemcp",
"containerDefinitions": [{
"name": "dollhousemcp",
"image": "ghcr.io/mickdarling/dollhousemcp:latest",
"memory": 512,
"cpu": 256,
"environment": [
{"name": "NODE_ENV", "value": "production"},
{"name": "PERSONAS_DIR", "value": "/app/personas"},
{"name": "DOLLHOUSE_USER", "value": "production"}
]
}]
}
Google Cloud Run
gcloud run deploy dollhousemcp \
--image ghcr.io/mickdarling/dollhousemcp:latest \
--platform managed \
--region us-central1 \
--set-env-vars NODE_ENV=production,DOLLHOUSE_USER=production
Azure Container Instances
az container create \
--name dollhousemcp \
--resource-group myResourceGroup \
--image ghcr.io/mickdarling/dollhousemcp:latest \
--environment-variables NODE_ENV=production DOLLHOUSE_USER=production
🛠️ Development
Available Scripts
| Script |
Description |
npm run build |
Compile TypeScript to JavaScript |
npm run start |
Run the compiled server |
npm run dev |
Run in development mode with auto-reload |
npm run clean |
Remove compiled files |
npm run rebuild |
Clean and rebuild the project |
npm run setup |
Install dependencies and build |
npm test |
Run the comprehensive test suite |
npm run test:coverage |
Run tests with coverage reporting |
Environment Variables
export DOLLHOUSE_USER="your-username"
export DOLLHOUSE_EMAIL="your-email"
export PERSONAS_DIR="/custom/path/to/personas"
export GITHUB_TOKEN="your-token"
export NODE_ENV="development"
export DEBUG="dollhousemcp:*"
🔧 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 |
| Collection 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 |
| Rate limit errors |
Wait 60 seconds; GitHub API has hourly limits |
Debug Steps
-
Check build status:
npm run build
-
Verify persona files:
ls -la personas/*.md
-
Test server startup:
node dist/index.js
-
Validate configuration:
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
node --version
npm --version
-
Test auto-update system:
check_for_updates
get_server_status
-
Validate personas:
Use the reload_personas tool to check for loading errors
🤝 Contributing
Integrated Contribution Process (Recommended)
-
Create or modify a persona using the chat-based tools:
create_persona "My Awesome Persona" "A helpful assistant for..." "professional"
-
Validate your persona to ensure quality:
validate_persona "My Awesome Persona"
-
Submit to the collection directly from Claude:
submit_persona "My Awesome Persona"
This automatically creates a GitHub issue for community review.
Manual Contribution Process
- Fork the repository
- Create persona files in
personas/ or custom-personas/
- Follow the metadata format and naming conventions
- Test thoroughly with
validate_persona tool
- Submit a pull request with clear description
Reporting Issues
Please include:
- Node.js version (
node --version)
- Operating system and version
- Complete error messages
- Steps to reproduce the issue
- Relevant persona files (if applicable)
- Claude Desktop configuration (without sensitive paths)
Development Guidelines
- Follow TypeScript best practices
- Maintain existing code style and patterns
- Add comprehensive error handling
- Update documentation for new features
- Test thoroughly across platforms before submitting PRs
- Include tests for new functionality
- Follow semantic versioning for releases
Development Workflow
git clone https://github.com/your-username/DollhouseMCP.git
cd mcp-server
npm install
git checkout -b feature/your-feature-name
npm run build
npm test
git commit -m "feat: your feature description"
git push origin feature/your-feature-name
📄 API Reference
MCP Tool Specifications
interface DollhouseTool {
name: string;
description: string;
inputSchema: {
type: "object";
properties: Record<string, any>;
required?: string[];
};
}
Tool Categories
Core Persona Management
Collection Integration
User Identity Management
Chat-Based Management
Auto-Update System
Error Handling
The server provides detailed error messages for:
- Invalid persona identifiers - Clear suggestions for valid names
- File system issues - Permission and path resolution errors
- Malformed persona files - YAML parsing and validation errors
- Network errors - GitHub API and collection connectivity issues
- Runtime errors - Server startup and operation failures
Response Formats
All responses follow consistent patterns:
- Success responses: Include requested data and operation status
- Error responses: Include error type, message, and suggested resolution
- Progress indicators: Step-by-step feedback for long operations
- Validation results: Detailed reports with recommendations
📄 License
This project is licensed under the AGPL-3.0 License with Platform Stability Commitments - see the LICENSE file for details.
Platform Stability Guarantees:
- 90-day advance notice for policy changes
- 12-month revenue sharing locks
- Full data portability rights
- Community advisory input
🏷️ Version History
v1.2.5 - July 2025 (Next Release)
Collection Rename & Breaking Changes:
- 🔄 Renamed all "marketplace" tools to "collection":
browse_marketplace → browse_collection
search_marketplace → search_collection
get_marketplace_persona → get_collection_persona
install_persona → install_persona (unchanged)
submit_persona → submit_persona (unchanged)
- ✅ Added backward compatibility aliases (deprecated, will be removed in v2.0.0)
- ✅ Updated repository from
/personas to /collection
- ✅ Created migration guide for users to update their scripts
- ✅ Fixed all date references from January to July 2025
v1.2.4 - July 10, 2025 (Current)
Critical Fix:
- ✅ Fixed MCP protocol compatibility - console output no longer breaks JSON-RPC communication
- ✅ Added MCP-safe logger utility for proper logging during protocol sessions
- ✅ Resolves connection failures in Claude Desktop
- ✅ Updated Docker tests to work with new logging approach
- ✅ Added comprehensive logger unit tests
v1.2.3 - July 10, 2025
Bug Fix:
- ✅ Fixed personas directory path resolution for production environments
- ✅ Changed from process.cwd() to __dirname-based paths
- ✅ Fixed setup script with correct tool count and repository URLs
v1.2.2 - July 10, 2025
- ✅ Comprehensive security enhancements:
- Content sanitization with DOMPurify (SEC-001)
- YAML injection prevention (SEC-003)
- GitHub token security (SEC-004)
- Docker container hardening (SEC-005)
- ✅ 487 comprehensive tests including extensive security coverage
- ✅ CI timing test fixes for reliable cross-platform testing
- ✅ TypeScript compilation fixes for all test files
- ✅ All security vulnerabilities resolved (0 active alerts)
v1.2.1 - July 8, 2025
- ✅ Critical bug fixes for data protection:
- Copy-on-write for default personas (Issue #145)
- User personas included in backups (Issue #144)
- ✅ Node.js 20+ requirement for npm publishing compatibility
- ✅ 372 comprehensive tests covering all functionality
- ✅ Enhanced security with all vulnerabilities resolved
- ✅ Improved documentation with clear prerequisites
v1.2.0 - July 7, 2025
- ✅ Rate limiting implementation to prevent API abuse
- ✅ GPG signature verification for release authenticity
- ✅ GitHub Advanced Security integration
- ✅ 309 tests with improved CI environment coverage
- ✅ Package optimization at 279.3 kB
v1.1.0 - July 4, 2025
- ✅ Platform-specific badges for Windows, macOS, Linux visibility
- ✅ GitHub Project management with issue templates and milestones
- ✅ ARM64 Docker fix switching from Alpine to Debian base images
- ✅ 100% workflow reliability (except Docker ARM64)
- ✅ First GitHub release with CHANGELOG.md
- ✅ 21 total MCP tools at time of release
Phase 2B+ - July 3, 2025
- ✅ Enterprise-grade auto-update system with 4 new MCP tools
- ✅ 50 comprehensive tests covering all functionality
- ✅ Security hardening - eliminated all command injection vulnerabilities
- ✅ Cross-platform support - Windows, macOS, Linux with CI/CD testing
- ✅ Docker containerization with production and development configurations
- ✅ 21 total MCP tools with backup/rollback and dependency validation
Phase 2B - July 1-2, 2025
- ✅ Complete chat-based persona management
- ✅ GitHub marketplace integration
- ✅ User identity and attribution system
- ✅ Real-time validation and editing
- ✅ Enterprise-grade GitHub Actions security
Phase 1 - July 1, 2025
- ✅ Fresh AGPL-3.0 licensed repository
- ✅ Enhanced unique ID system
- ✅ Anonymous user support
- ✅ Marketplace-ready metadata schema
🎭 Transform your AI interactions with the power of personas
For support, please open an issue or visit our collection.