Offers containerized deployment options with production and development configurations, supporting volume mounts for custom personas and environment variable configuration
Provides a complete GitHub-powered marketplace integration for browsing, searching, installing, and submitting personas, with support for authentication and automated submission workflows
DollhouseMCP
Platform Support
A comprehensive Model Context Protocol (MCP) server that enables dynamic AI persona management with an integrated GitHub-powered marketplace. DollhouseMCP allows Claude and other compatible AI assistants to activate different behavioral personas while supporting community sharing and monetization.
🌐 Repository: https://github.com/mickdarling/DollhouseMCP
🏪 Marketplace: https://github.com/mickdarling/DollhouseMCP-Personas
🌍 Website: https://dollhousemcp.com (planned)
✨ Key Features
Feature | Description |
---|---|
🎭 23 MCP Tools | Complete persona lifecycle management through chat interface |
🏪 GitHub Marketplace | Browse, search, install, and submit personas to community marketplace |
👤 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 |
🏠 Local-First Architecture | Full functionality without cloud dependency |
🚀 Quick Start
Installation
Automated Setup (Recommended) - 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.
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.
Claude Desktop Configuration
Add DollhouseMCP to your Claude Desktop configuration:
Location: ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS)
🔄 After configuration:
- Save the file
- Restart Claude Desktop completely
- All 23 DollhouseMCP tools will be available
🛠️ Available Tools (23 Total)
Core Persona Management
list_personas
- Display all local personas with enhanced metadataactivate_persona
- Activate by name, filename, or unique IDget_active_persona
- Get current persona informationdeactivate_persona
- Return to default modeget_persona_details
- View complete persona detailsreload_personas
- Refresh from filesystem
GitHub Marketplace Integration
browse_marketplace
- Browse personas by categorysearch_marketplace
- Search across all marketplace personasget_marketplace_persona
- View detailed marketplace persona infoinstall_persona
- One-click download and installationsubmit_persona
- Submit to marketplace via GitHub issue
User Identity Management
set_user_identity
- Set username for persona attributionget_user_identity
- View current identity statusclear_user_identity
- Return to anonymous mode
Chat-Based Persona Management
create_persona
- Guided persona creation through chatedit_persona
- Modify existing persona fieldsvalidate_persona
- Comprehensive quality validation
Auto-Update System
check_for_updates
- Check GitHub releases for available DollhouseMCP updatesupdate_server
- Automated git pull + npm install + build with backup creationrollback_update
- Restore previous version from automatic backupsget_server_status
- Comprehensive server status with version, git info, and system details
Persona Indicators
configure_indicator
- Configure how persona indicators appear in AI responsesget_indicator_config
- View current indicator configuration settings
📖 Usage Examples
Marketplace Operations
Persona Creation & Management
User Identity
Auto-Update Operations
Persona Indicators
DollhouseMCP adds visual indicators to AI responses when a persona is active:
Configure indicators:
Environment variables for persistent configuration:
🖥️ Cross-Platform Installation
🐧 Linux Installation
Prerequisites
Installation Steps
Claude Desktop Configuration (Linux)
Configuration content:
🪟 Windows Installation
Prerequisites
Installation Steps (PowerShell)
Claude Desktop Configuration (Windows)
Configuration content (use forward slashes or double backslashes):
🍎 macOS Installation
Prerequisites
Installation Steps
Claude Desktop Configuration (macOS)
Configuration content:
🐳 Docker Installation
Quick Start with Docker
Docker Compose (Recommended)
Production deployment:
Development with hot reload:
Custom Personas with Docker
Docker Environment Variables
🧪 Testing
Running Tests
The project includes comprehensive tests for cross-platform compatibility:
Test Coverage
Current test coverage includes:
- ✅ 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
Verify your setup works correctly:
☁️ Cloud Deployment
Container Registries
The project supports deployment to:
- GitHub Container Registry (ghcr.io)
- Docker Hub
- AWS ECR
- Google Container Registry
Example Cloud Deployments
AWS ECS
Google Cloud Run
Azure Container Instances
🏗️ Project Structure
📝 Creating Custom Personas
Enhanced Persona Format
Create .md
files in the personas/
directory with this structure:
Metadata Fields
Field | Required | Description |
---|---|---|
name | ✅ | Display name for the persona |
description | ✅ | Brief description of purpose |
unique_id | ❌ | Auto-generated if missing |
author | ❌ | Creator username (uses environment or anonymous) |
category | ❌ | creative, professional, educational, gaming, personal |
triggers | ❌ | Keywords that suggest this persona |
version | ❌ | Version tracking |
age_rating | ❌ | all, 13+, 18+ |
ai_generated | ❌ | Boolean flag for AI-created content |
price | ❌ | "free" or monetary amount |
📚 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 |
🏪 Marketplace Integration
DollhouseMCP includes a complete GitHub-powered marketplace:
- Browse by Category: creative, professional, educational, gaming, personal
- Search Content: Find personas by keywords and descriptions
- One-Click Install: Download and integrate marketplace personas
- Community Submissions: Submit your personas via automated GitHub workflow
- Version Control: Full Git history for all marketplace content
💼 Business Model & Legal
Licensing
- Core Server: AGPL-3.0 (prevents proprietary competing platforms)
- Platform Terms: Creator-friendly 80/20 revenue split framework
- Persona Content: CC-BY-SA-4.0 for free personas
Platform Stability Commitments
- 90-day advance notice for monetization changes
- 12-month revenue sharing locks
- Full data portability rights
- Community advisory input on policy changes
🛠️ 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
Customize server behavior with these environment variables:
🔧 Troubleshooting
Common Issues
Issue | Solution |
---|---|
Personas not loading | Check personas/ directory and file 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 | Verify environment variables are set correctly |
Debug Steps
- Check build status:
- Verify persona files:
- Test server startup:
- Validate configuration:
- Test auto-update system:
- Validate personas:
Use the
reload_personas
tool to check for loading errors
🤝 Contributing
We welcome contributions! Here's how to help:
Adding Personas
- Fork the repository
- Create a new persona file in
personas/
- Follow the established format and naming conventions
- Test your persona thoroughly with
validate_persona
tool - Submit a pull request with a clear description
Community Contributions
- Create personas following the enhanced metadata format
- Test thoroughly with
validate_persona
tool - Submit via
submit_persona
tool for community review - Participate in GitHub discussions and issue reviews
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
📄 API Reference
MCP Tool Specifications
Each tool follows the MCP specification:
Tool Categories
Core Persona Management
Marketplace 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 marketplace 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
Unreleased (Current)
- ✅ Persona active indicator system with 2 new MCP tools (Issue #31)
- ✅ 102 comprehensive tests covering all functionality
- ✅ 23 total MCP tools including configure_indicator and get_indicator_config
- ✅ Enhanced documentation with Claude Desktop setup clarifications
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 marketplace.
This server cannot be installed
A comprehensive Model Context Protocol server that enables dynamic AI persona management with GitHub-powered marketplace integration, allowing Claude and other compatible AI assistants to activate different behavioral personas with community sharing capabilities.
- Platform Support
- ✨ Key Features
- 🚀 Quick Start
- 🛠️ Available Tools (23 Total)
- 📖 Usage Examples
- 🖥️ Cross-Platform Installation
- 🐳 Docker Installation
- 🧪 Testing
- ☁️ Cloud Deployment
- 🏗️ Project Structure
- 📝 Creating Custom Personas
- 📚 Built-in Personas
- 🏪 Marketplace Integration
- 💼 Business Model & Legal
- 🛠️ Development
- 🔧 Troubleshooting
- 🤝 Contributing
- 📄 API Reference
- 📄 License
- 🏷️ Version History
Related MCP Servers
- -securityFlicense-qualityA comprehensive suite of Model Context Protocol servers designed to extend AI agent Claude's capabilities with integrations for knowledge management, reasoning, advanced search, news access, and workspace tools.Last updated -5TypeScript
- AsecurityAlicenseAqualityA Model Context Protocol server that enables AI assistants like Claude to interact with Google Cloud Platform environments through natural language, allowing users to query and manage GCP resources during conversations.Last updated -910262TypeScriptMIT License
- -securityAlicense-qualityA Model Context Protocol server that connects Claude and other MCP clients to Aider, enabling AI assistants to efficiently edit files, create new files, and interact with git repositories through natural language.Last updated -9PythonThe Unlicense
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants like Claude to interact directly with Home Assistant, allowing them to query device states, control smart home entities, and perform automation tasks.Last updated -104PythonMIT License