DollhouseMCP

DollhouseMCP

Open-source AI customization through modular elements.

Website · Browse the Collection · NPM Package · Discord

---

How It Works

 CREATE or EDIT                    PORTFOLIO                   ACTIVATE → USE

─────────────────────────────────────────────────────────────────────────────

"Create a skill for 📁 ~/.dollhouse/portfolio/ "Activate the Dollhouse writing blog posts" Expert ensemble" 37 starter elements: "Edit the code review ──▶ personas · skills · ──▶ Your AI now has persona to add security" templates · agents · new behavior, memories · ensembles capabilities, and persona · skill · template permission policies agent · memory · ensemble + everything you create

• community installs

Pick any path to start:

• Activate a starter element from your portfolio — your AI immediately changes
• Create any element type (persona, skill, template, agent, memory, ensemble) by describing what you want in plain English
• Edit any existing element to refine it
• Browse the community collection and install elements made by other users

Your portfolio (~/.dollhouse/portfolio/ on macOS/Linux, %USERPROFILE%\.dollhouse\portfolio\ on Windows) is a local folder that holds all your Dollhouse elements. It ships with 37 starters — including the dollhouse-expert-suite ensemble (persona + knowledge base) you can activate for guided help. Everything you create or install lands here. Share back to the community or sync to GitHub whenever you're ready.

---

Quick Start

v2.0.0 is now available. DollhouseMCP v2 is the default release. Release notes | Migration guide | Report issues

DollhouseMCP installs on any MCP-compatible AI client — Claude Code, Claude Desktop, Cursor, Gemini, Codex, and local LLMs. Core element management (create, activate, search, browse) works across all platforms. Advanced features (Gatekeeper confirmation flows, agentic loop execution) have been tested extensively on Claude Code and should work on any client that supports standard MCP tool call/response patterns.

Interactive Setup (any platform):

npx @dollhousemcp/mcp-server@latest --web

Opens a browser-based setup wizard with one-click install for Claude Desktop, Claude Code, Cursor, VS Code, Codex, Gemini CLI, Windsurf, Cline, and LM Studio. Detects existing installations, supports auto-updating and pinned versions.

Permission hook support in the setup wizard currently breaks down like this:

Claude Code (one command):

claude mcp add -s user dollhousemcp -- npx -y @dollhousemcp/mcp-server

Claude Desktop (one-click install):

Download the DollhouseMCP Desktop Extension (.mcpb file) and double-click it. Claude Desktop handles the rest — no terminal required.

Other platforms — see the Quick Start Guide or run the interactive setup above.

Then start a conversation:

"What DollhouseMCP tools do you have available?"

"List all available Dollhouse personas" "Activate the Dollhouse debug detective persona"

DollhouseMCP ships with 38 Dollhouse elements across all 6 types. Just describe what you want in natural language.

First time? The Public Beta Onboarding Guide walks you from install to your first activated Dollhouse persona in under 10 minutes.

---

Dollhouse Elements: Behavior, Capabilities, and Permissions

Dollhouse elements are modular building blocks that customize your AI. When you activate a Dollhouse element, you're not just changing a prompt — you're changing what tools the AI can access, what commands it can run, and what operations require your approval.

| Dollhouse Personas | Shape behavior, tone, expertise, and priorities. Act as security principals with permission policies that control what the AI can do. | | Dollhouse Skills* | Add discrete capabilities the AI can activate on demand. Code review, data analysis, penetration testing, translation, and more. | | Dollhouse Templates | Standardize outputs with variable substitution. Reports, emails, briefs, documentation — consistent structure every time. Variables are auto-derived from {{placeholder}} tokens in content — no manual schema needed. | | Dollhouse Agents | Execute multi-step goals autonomously. State tracking, resilience policies, autonomy evaluation, and an execution lifecycle. | | Dollhouse Memories | Persist structured context across sessions. Facts, preferences, project state. Can auto-load on startup. | | Dollhouse Ensembles | Bundle multiple elements into one activatable unit. Activation strategies, conflict resolution, and coordinated permission policies. |

**\*Skills Compatibility**

Dollhouse Skills (introduced July 2025) predate the agent skills format later adopted by Claude/Anthropic. DollhouseMCP includes a built-in lossless bidirectional converter between the two formats.

- Import: Convert agent skills → Dollhouse Skills via convert_skill_format. Once converted, they're first-class Dollhouse elements — combinable with Personas, Templates, and other Skills inside Ensembles, managed by Dollhouse Agents, and protected by Gatekeeper policies.

- Export: Convert Dollhouse Skills → agent skills for platforms that don't have DollhouseMCP installed.

- Roundtrip: The converter supports a lossless mode that preserves everything in both directions. A safe mode is also available that sanitizes potentially risky patterns during conversion.

Full Skills Converter documentation

All Dollhouse elements are readable markdown or YAML files stored in your local portfolio. You own them, you control them. When interacting with your AI, use "Dollhouse" to disambiguate — say "activate the Dollhouse code review persona" or "run the Dollhouse research agent" to ensure the AI uses DollhouseMCP elements rather than native platform features.

---

MCP-AQL: How Your AI Talks to DollhouseMCP

Most MCP servers expose dozens of individual tools, each consuming context tokens and forcing the LLM to pick the right one from a flat list. DollhouseMCP takes a different approach.

MCP-AQL (Model Context Protocol – Advanced Agent API Adapter Query Language) organizes all operations into 5 semantic endpoints — CRUDE: Create, Read, Update, Delete, Execute. The A pulls quadruple duty: Advanced query capabilities, Agent-first design, API consolidation, and Adapter layer to bridge other MCP servers and APIs to work directly with LLMs. Each endpoint groups operations by what they do to state, giving the LLM clear semantic signals about the consequences of each action:

Why This Matters

• Semantic clarity — The LLM knows that calling mcp_aql_read is always safe. Calling mcp_aql_delete is always destructive. No guessing.
• Host-level permission control — MCP clients like Claude Code can set different approval policies per endpoint (auto-approve reads, require confirmation for deletes).
• Progressive disclosure through introspection — The LLM starts with just 5 tool endpoints. It discovers operations, parameters, element formats, and usage examples at runtime by asking the server:

  { "operation": "introspect", "params": { "query": "operations" } }

{ "operation": "introspect", "params": { "query": "format", "name": "persona" } }

This is progressive disclosure built into the protocol — the LLM only loads what it needs, when it needs it. Unlike client-side solutions that require special harness support (like Claude Code's deferred tool loading), MCP-AQL's introspection works on any MCP client because it's just a standard tool call that returns structured data. No fancy client features required. The server describes itself.

Eleme