Persona Switcher MCP Server

Dynamic AI persona management for Claude with file-based storage. Switch between different AI personas mid-conversation or start conversations with pre-configured personas.

Features

• Dynamic Persona Prompts: Start conversations with specific personas from Claude Desktop's prompt selector
• Mid-Conversation Switching: Activate different personas without losing conversation context
• File-Based Storage: Personas stored as markdown files with YAML frontmatter for easy editing and version control
• CRUD Operations: Create, read, update, and delete personas through MCP tools
• Zero Configuration: Works out of the box with sensible defaults
• Automatic Initialization: Creates example persona on first run
• Validation: Built-in input validation for persona names, descriptions, and instructions
• Error Handling: Comprehensive error messages with helpful suggestions

Requirements

• Python 3.10 or higher
• Claude Desktop (for integration)
• At least 10MB disk space for persona files

Installation

1. Clone or Download

cd "persona-switcher-mcp Project"
cd persona-switcher-mcp

2. Create Virtual Environment

python -m venv venv

Activate the virtual environment:

• Windows: venv\Scripts\activate
• macOS/Linux: source venv/bin/activate

3. Install Dependencies

pip install -r requirements.txt

For development (includes testing tools):

pip install -r requirements-dev.txt

4. Install as Editable Package (Optional)

pip install -e .

Configuration

Environment Variables

All configuration is optional. Create a .env file if you want to customize:

# Copy example configuration
cp .env.example .env

Available options:

Variable	Default	Description
PERSONAS_DIR	./personas	Path to personas directory
LOG_LEVEL	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
AUTO_RELOAD	false	Auto-reload prompts when files change (requires watchdog)

Claude Desktop Configuration

Add to your claude_desktop_config.json:

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

{
  "mcpServers": {
    "persona-switcher": {
      "command": "python",
      "args": [
        "C:/Users/YourUsername/path/to/persona-switcher-mcp/src/server.py"
      ],
      "env": {
        "PERSONAS_DIR": "C:/Users/YourUsername/path/to/persona-switcher-mcp/personas",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Important: Use absolute paths and forward slashes (/) even on Windows.

After adding the configuration, restart Claude Desktop.

Usage

Testing with MCP Inspector

Before integrating with Claude Desktop, test the server with MCP Inspector:

npx @modelcontextprotocol/inspector python src/server.py

Open http://localhost:6274 in your browser to interact with the server.

Creating Personas

Personas are stored as markdown files with YAML frontmatter in the personas/ directory.

File Format

---
name: Code Reviewer
description: Expert code reviewer focusing on best practices, security, and performance
version: 1.0
author: User
---

You are an expert code reviewer with deep knowledge of software engineering best practices.

Your focus areas:
- Code quality and maintainability
- Security vulnerabilities
- Performance optimization
- Design patterns
- Testing coverage

When reviewing code, provide:
1. Overall assessment
2. Specific issues with line references
3. Actionable recommendations
4. Security concerns (if any)

Be thorough but constructive in your feedback.

Naming Rules

• Filename pattern: ^[a-z0-9-]+\.md$
• Lowercase letters only
• Numbers allowed
• Hyphens for word separation
• No spaces, underscores, or special characters

Valid: code-reviewer.md, technical-writer.md, python-expert.md Invalid: Code-Reviewer.md, code_reviewer.md, code reviewer.md

Available Tools

1. list_personas

List all available personas with their metadata.

Parameters: None

Returns:

{
  "personas": [
    {
      "name": "Code Reviewer",
      "description": "Expert code reviewer...",
      "version": "1.0",
      "author": "User",
      "filename": "code-reviewer"
    }
  ],
  "count": 1
}

Example Usage:

User: "What personas are available?"
Claude: *calls list_personas()*
Claude: "You have 3 personas available: Code Reviewer, Technical Writer, and Creative Brainstormer."

2. activate_persona

Load and activate a persona's instructions mid-conversation.

Parameters:

• name (string): Persona name (filename without .md)

Returns:

{
  "success": true,
  "persona_name": "Code Reviewer",
  "instructions": "You are an expert code reviewer...",
  "metadata": {
    "description": "Expert code reviewer...",
    "version": "1.0",
    "author": "User"
  }
}

Example Usage:

User: "Switch to code reviewer mode"
Claude: *calls activate_persona({name: "code-reviewer"})*
Claude: "I've activated the Code Reviewer persona. I'm now ready to review your code with a focus on best practices, security, and performance."

3. create_persona

Create a new persona file.

Parameters:

• name (string): Persona name (lowercase with hyphens, 1-50 chars)
• description (string): Brief description (10-200 chars)
• instructions (string): Full instructions (minimum 20 chars)
• author (string, optional): Author name (default: "User")

Returns:

{
  "success": true,
  "persona_name": "python-expert",
  "file_path": "personas/python-expert.md",
  "message": "Persona 'python-expert' created successfully"
}

Example Usage:

User: "Create a Python expert persona"
Claude: *calls create_persona({
  name: "python-expert",
  description: "Python programming expert specialized in best practices",
  instructions: "You are a Python expert with deep knowledge of...",
  author: "User"
})*
Claude: "I've created the Python Expert persona. You can activate it anytime or start a new conversation with it from the prompt selector."

4. edit_persona

Update an existing persona's metadata or instructions.

Parameters:

• name (string): Persona name
• field (string): Field to update (description, instructions, author, or version)
• value (string): New value

Returns:

{
  "success": true,
  "persona_name": "code-reviewer",
  "field_updated": "description",
  "message": "Persona 'code-reviewer' updated successfully"
}

Example Usage:

User: "Update the code reviewer's instructions to focus more on security"
Claude: *calls edit_persona({
  name: "code-reviewer",
  field: "instructions",
  value: "You are an expert code reviewer with primary focus on security vulnerabilities..."
})*
Claude: "I've updated the Code Reviewer persona to emphasize security in code reviews."

5. delete_persona

Remove a persona file from the personas directory.

Parameters:

• name (string): Persona name
• confirm (boolean): Must be true to confirm deletion

Returns:

{
  "success": true,
  "persona_name": "old-persona",
  "message": "Persona 'old-persona' deleted successfully"
}

Example Usage:

User: "Delete the old-persona"
Claude: *calls delete_persona({name: "old-persona", confirm: true})*
Claude: "I've deleted the old-persona. It's no longer available."

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_validators.py

# Run with verbose output
pytest -v

Project Structure

persona-switcher-mcp/
├── src/
│   ├── __init__.py           # Package initialization
│   ├── server.py             # FastMCP server and tools
│   ├── persona_manager.py    # Business logic (CRUD operations)
│   ├── validators.py         # Input validation functions
│   ├── errors.py            # Custom exception classes
│   ├── config.py            # Configuration management
│   └── utils.py             # Utility functions (atomic writes)
├── personas/                 # Persona markdown files
│   ├── example.md           # Example persona (created automatically)
│   └── *.md                 # User-created personas
├── tests/
│   ├── conftest.py          # Pytest fixtures
│   ├── test_validators.py  # Validator tests
│   ├── test_persona_manager.py  # PersonaManager tests
│   ├── test_server.py       # Integration tests
│   └── fixtures/            # Test data files
├── pyproject.toml           # Python project configuration
├── requirements.txt         # Production dependencies
├── requirements-dev.txt     # Development dependencies
├── README.md               # This file
├── .env.example            # Example environment configuration
├── .gitignore              # Git ignore rules
└── LICENSE                 # MIT License

Code Quality

The codebase follows these principles:

• Layered Architecture: Clear separation between presentation (server.py), business logic (persona_manager.py), and utilities
• Input Validation: All inputs validated before processing
• Error Handling: Comprehensive error classes with helpful messages
• Atomic File Operations: Prevents file corruption during writes
• Logging: All operations logged to stderr for debugging
• Type Hints: Python 3.10+ type hints throughout
• Documentation: Docstrings for all public functions and classes

Troubleshooting

Server Won't Start

Error: "Personas directory not found" Solution: The server will automatically create the directory. Check file permissions.

Error: "Module not found" Solution: Ensure virtual environment is activated and dependencies are installed:

source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

Personas Not Appearing in Claude Desktop

Issue: Prompts don't show up in the prompt selector

Solutions:

1. Verify server is configured correctly in claude_desktop_config.json
2. Use absolute paths in the configuration
3. Restart Claude Desktop after configuration changes
4. Check Claude Desktop logs for errors
5. Verify persona files have valid YAML frontmatter with name and description fields

Tool Calls Failing

Error: "Persona not found" Solution:

• Use list_personas() to see available personas
• Check that the persona name matches the filename (without .md extension)
• Ensure persona file has valid YAML frontmatter

Error: "Validation error" Solution:

• Persona names must be lowercase with hyphens only
• Descriptions must be 10-200 characters
• Instructions must be at least 20 characters

File Permission Errors

Error: "Permission denied" or "Cannot write to personas directory"

Solutions:

• Check directory permissions: ls -la personas/
• Make directory writable: chmod u+w personas/
• On Windows, check folder properties and ensure write permission

Logs Not Appearing

Issue: Can't see server logs

Solution: Logs are written to stderr. When running with MCP Inspector or Claude Desktop, check:

• Terminal output where you started the server
• Claude Desktop logs (check application logs directory)
• Set LOG_LEVEL=DEBUG in .env for more detailed logs

Example Personas

Code Reviewer

File: personas/code-reviewer.md

---
name: Code Reviewer
description: Expert code reviewer focusing on best practices, security, and performance
version: 1.0
author: System
---

You are an expert code reviewer with deep knowledge of software engineering best practices.

Your focus areas:
- Code quality and maintainability
- Security vulnerabilities (OWASP Top 10)
- Performance optimization
- Design patterns and architecture
- Testing coverage and quality

When reviewing code, provide:
1. Overall assessment of code quality
2. Specific issues with line references
3. Actionable recommendations for improvement
4. Security concerns (if any)
5. Performance implications

Be thorough but constructive in your feedback. Explain the "why" behind each suggestion.

Technical Writer

File: personas/technical-writer.md

---
name: Technical Writer
description: Professional technical writer specializing in clear, concise documentation
version: 1.0
author: System
---

You are a professional technical writer with expertise in creating clear, user-friendly documentation.

Your specialties:
- API documentation
- User guides and tutorials
- README files
- Technical specifications
- Code comments and docstrings

Your writing principles:
- Clarity over cleverness
- Active voice over passive
- Examples for complex concepts
- Consistent terminology
- Proper formatting and structure

When writing documentation:
1. Start with a clear summary
2. Explain the "what" and "why"
3. Provide code examples
4. Include edge cases and limitations
5. End with troubleshooting tips

Creative Brainstormer

File: personas/creative-brainstormer.md

---
name: Creative Brainstormer
description: Innovative thinker generating creative ideas and solutions
version: 1.0
author: System
---

You are a creative brainstorming partner with a knack for innovative thinking and problem-solving.

Your approach:
- Think divergently before converging
- Explore unconventional angles
- Build on ideas iteratively
- Combine concepts in novel ways
- Challenge assumptions

When brainstorming:
1. Generate multiple diverse ideas (quantity over quality initially)
2. Explore "what if" scenarios
3. Look for unexpected connections
4. Question constraints
5. Refine promising concepts

Be enthusiastic, open-minded, and constructive. No idea is too wild in the brainstorming phase.

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built with FastMCP - The official Python SDK for MCP servers
• Inspired by the MCP Persona Server concept
• Follows MCP Best Practices

Support

• Issues: Report bugs or request features via GitHub Issues
• Documentation: See the MCP Documentation
• FastMCP Docs: https://gofastmcp.com

---

Version: 1.0.0 Status: Production Ready Last Updated: 2025-11-09