DollhouseMCP
DollhouseMCP
A comprehensive Model Context Protocol (MCP) server that enables dynamic AI persona management with an integrated GitHub-powered collection. DollhouseMCP allows Claude and other compatible AI assistants to activate different behavioral personas while supporting community sharing and monetization.
🌐 Repository: https://github.com/DollhouseMCP/mcp-server
🏪 Collection: https://github.com/DollhouseMCP/collection
📦 NPM Package: https://www.npmjs.com/package/@dollhousemcp/mcp-server
🌍 Website: https://dollhousemcp.com (planned)
🚀 Quick Start
Choose Your Installation Method
| Method | Best For | Pros | Cons |
|---|---|---|---|
| Local Install (Recommended) |
Most users, multiple configs, customization | ✅ Multiple setups ✅ Easy backup ✅ No permissions |
❌ Longer path in config |
| npx | Quick testing, always latest | ✅ No install ✅ Always updated |
❌ Slower startup ❌ Needs internet |
| Global Install | Single shared instance | ✅ Short command | ❌ Only one version ❌ Needs sudo/admin |
Method 1: Local Installation (Recommended)
Create a dedicated folder for your MCP servers and install there:
# Create MCP servers directory
mkdir ~/mcp-servers
cd ~/mcp-servers
# Install DollhouseMCP
npm install @dollhousemcp/mcp-serverConfigure Claude Desktop:
Add to your config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"dollhousemcp": {
"command": "node",
"args": ["/Users/YOUR_USERNAME/mcp-servers/node_modules/@dollhousemcp/mcp-server/dist/index.js"]
}
}
}💡 Pro tip: Replace /Users/YOUR_USERNAME with your actual home directory path.
Method 2: Always Latest with npx
No installation needed! Configure Claude Desktop to always use the latest version:
{
"mcpServers": {
"dollhousemcp": {
"command": "npx",
"args": ["@dollhousemcp/mcp-server@latest"]
}
}
}📝 Note: The @latest tag ensures you always get the newest version. Remove it to use npm's cached version.
Method 3: Global Installation
# Install globally (may require sudo/admin)
npm install -g @dollhousemcp/mcp-serverConfigure Claude Desktop:
{
"mcpServers": {
"dollhousemcp": {
"command": "dollhousemcp"
}
}
}⚠️ Warning: Only one version system-wide. Consider local installation for more flexibility.
🎯 Advanced: Multiple Configurations
Want separate portfolios for different contexts? Create multiple local installations:
# Personal assistant
mkdir ~/mcp-servers/personal
cd ~/mcp-servers/personal
npm install @dollhousemcp/mcp-server
# Work assistant
mkdir ~/mcp-servers/work
cd ~/mcp-servers/work
npm install @dollhousemcp/mcp-server
# Creative writing
mkdir ~/mcp-servers/creative
cd ~/mcp-servers/creative
npm install @dollhousemcp/mcp-serverConfigure each with its own portfolio:
{
"mcpServers": {
"dollhouse-personal": {
"command": "node",
"args": ["/Users/YOU/mcp-servers/personal/node_modules/@dollhousemcp/mcp-server/dist/index.js"],
"env": {
"DOLLHOUSE_PORTFOLIO_DIR": "/Users/YOU/portfolios/personal"
}
},
"dollhouse-work": {
"command": "node",
"args": ["/Users/YOU/mcp-servers/work/node_modules/@dollhousemcp/mcp-server/dist/index.js"],
"env": {
"DOLLHOUSE_PORTFOLIO_DIR": "/Users/YOU/portfolios/work"
}
}
}
}Now you can enable/disable different configurations in Claude Desktop as needed!
✅ Verify Installation
After configuring and restarting Claude Desktop, test with:
list_elements type="personas"You should see your available personas. If not, check the Troubleshooting section.
📁 Default Portfolio Location
By default, your elements are stored in:
- macOS/Linux:
~/.dollhouse/portfolio/ - Windows:
%USERPROFILE%\.dollhouse\portfolio\
Use the DOLLHOUSE_PORTFOLIO_DIR environment variable to customize this location.
🎯 Getting Started
Once installed, try these commands in Claude:
# Browse available personas
list_elements type="personas"
# Activate a persona
activate_element name="creative-writer" type="personas"
# Browse the community collection
browse_collection type="personas"
# Search for specific content
search_collection query="python" type="skills"📘 New User? Follow our Roundtrip Workflow Guide for a complete walkthrough of discovering, customizing, and sharing AI elements with the community.
✨ Key Features
| Feature | Description |
|---|---|
| 🎭 41 MCP Tools | Complete portfolio element management through chat interface |
| 🏪 GitHub Collection | Browse, search, install, and submit personas to community collection |
| 🔄 Roundtrip Workflow | Complete cycle: discover → customize → share → collaborate |
| 📁 GitHub Portfolio | Personal repository for storing and versioning your AI elements |
| 👤 User Identity System | Environment-based attribution for persona creators |
| 🆔 Unique ID System | Advanced ID generation: {type}_{name}_{author}_{YYYYMMDD}-{HHMMSS} |
| 💬 Chat-Based Management | Create, edit, and validate personas through conversational interface |
| 🔄 Real-time Operations | Live editing with automatic version bumping and validation |
| 📦 NPM Installation | Install MCP servers from npm with cross-platform support and atomic operations |
| 🛡️ Data Protection | Copy-on-write for default personas, comprehensive backup system |
| 🏠 Local-First Architecture | Full functionality without cloud dependency |
🎨 Portfolio Elements
DollhouseMCP supports multiple element types for customizing AI behavior:
| Element | Purpose | Status |
|---|---|---|
| 🎭 Personas | Define AI personality, tone, and behavioral characteristics | ✅ Available |
| 🛠️ Skills | Add specific capabilities like code review, data analysis, or creative writing | ✅ Available |
| 📝 Templates | Create reusable response formats for emails, reports, documentation | ✅ Available |
| 🤖 Agents | Build autonomous assistants that can pursue goals and make decisions | ✅ Available |
| 💬 Prompts | Pre-configured conversation starters and structured interactions | 🔄 Coming Soon |
| 🧠 Memory | Persistent context storage with retention policies and search capabilities | 🔄 Coming Soon |
| 🎯 Ensemble | Orchestrate multiple elements together as one unified entity | 🔄 Coming Soon |
Your portfolio lives in ~/.dollhouse/portfolio/ with elements organized by type.
🔧 Troubleshooting
Common Issues
| Issue | Solution |
|---|---|
| Personas not loading | Check ~/.dollhouse/portfolio/personas/ directory exists |
| Server won't start | Ensure Node.js v20+ is installed: node --version |
| Collection not working | Check internet connection and GitHub API access |
| Tools not appearing in Claude | Restart Claude Desktop completely after config changes |
| "Cannot find module" errors | Reinstall: npm install -g @dollhousemcp/mcp-server@latest |
| Rate limit errors | Wait 60 seconds; GitHub API has hourly limits |
Need Help?
📚 Resources
Documentation
- Roundtrip Workflow Guide
- Portfolio Setup Guide
- Element Detection Guide
- PersonaTools Migration Guide
- API Documentation
Community
- GitHub Repository
- NPM Package
- Community Collection
- Discord Community (coming soon)
Development
📄 License
DollhouseMCP is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
What this means:
- ✅ Free to use for personal and commercial purposes
- ✅ Modify and distribute with the same license
- ✅ Network use requires source code disclosure
- ✅ Platform stability commitments protect users
See LICENSE for full terms.
Built with ❤️ by the DollhouseMCP team