README.md
An expert role selector for Claude to switch AI personas.
Claude Role Library
An expert role selector for Claude - seamlessly switch AI personas in Claude Code CLI and Claude Desktop.
Overview
Claude Role Library is an MCP (Model Context Protocol) server that enables users to manage and apply specialized AI roles within the Claude ecosystem. Similar in concept to OpenAI's GPT Store, it provides a local-first approach to organizing and using curated prompts.
Key Features
- Cross-platform support - Works with both Claude Code CLI and Claude Desktop via MCP
- Local-first architecture - All data stored locally, no cloud dependency
- Two-tier favorites - Global and project-level role collections
- Source tracking - Track prompt origins with sync capabilities
- YAML-based storage - Human-readable, Git-friendly configuration
Installation
From npm (Coming Soon)
# Global installation
npm install -g claude-role-library
# Or use directly with npx
npx claude-role-library
Local Development
Prerequisites: Bun v1.0 or later
# Clone the repository
git clone https://github.com/user/claude-role-library.git
cd claude-role-library
# Install dependencies
bun install
# Run the server
bun run start
# Run in development mode (with hot reload)
bun run dev
Running Tests
# Run all tests
bun test
# Run tests in watch mode
bun test --watch
# Run specific test file
bun test src/schemas/role.test.ts
MCP Configuration
After npm install (future):
{
"mcpServers": {
"claude-role-library": {
"command": "npx",
"args": ["claude-role-library"]
}
}
}
For local development:
{
"mcpServers": {
"claude-role-library": {
"command": "bun",
"args": ["run", "/path/to/claude-role-library/src/index.ts"]
}
}
}
Usage
# List all available roles
/roles list
# Search for specific roles
/roles search "code review"
# Apply a role to the current session
/roles use senior-code-reviewer
# Manage favorites
/favorites list
/favorites add senior-code-reviewer
Data Structure
~/.config/claude-role-library/
├── config.yaml # Global configuration
├── sources.yaml # External source definitions
├── favorites.yaml # Favorited roles
└── roles/ # Role definitions
└── *.yaml
{project}/.claude-role-library/
└── favorites.yaml # Project-specific favorites
Tech Stack
| Component | Technology |
|---|---|
| Language | TypeScript |
| Runtime | Bun |
| Protocol | MCP SDK |
| Storage | YAML |
| Validation | Zod |
Documentation
- Architecture - System design and component overview
- Schema - Data format specifications
- Roadmap - Development progress and planned features
Roadmap
| Phase | Status | Features |
|---|---|---|
| Phase 1 | Completed | Core role management, MCP integration |
| Phase 2 | Completed | GitHub source sync, batch import |
| Phase 3 | In Progress | AI-assisted transformation, multi-source parsers, indexing |
| Phase 4 | Planned | Community sharing, usage statistics |
Contributing
Contributions are welcome. Please review the architecture documentation before submitting changes.
License
MIT
Tools (5)
roles listList all available AI roles.roles searchSearch for specific roles based on a query.roles useApply a specific role to the current session.favorites listList all favorited roles.favorites addAdd a role to the favorites collection.Configuration
claude_desktop_config.json
{"mcpServers": {"claude-role-library": {"command": "npx", "args": ["claude-role-library"]}}}Try it
→List all available roles to see what personas I can switch to.
→Search for roles related to code review.
→Apply the senior-code-reviewer role to my current session.
→Add the senior-code-reviewer role to my favorites list.