superpowers-mcp

An MCP server that makes superpowers skills available to any LLM that supports the Model Context Protocol.

Superpowers is a skills library for Claude Code that enforces disciplined workflows -- TDD, systematic debugging, brainstorming, planning, and more. This server exposes those skills to any MCP-compatible client: Cursor, Windsurf, Gemini, Kilo Code, Claude Desktop, or your own app.

What It Exposes

The server registers skills through all three MCP primitives:

Tools

Prompts

Each skill is registered as an MCP prompt named superpowers:{skill-name}. Clients that support prompt selection will show these in their UI. Selecting a prompt injects the full skill content into the conversation.

Resources

Each skill's SKILL.md and supporting files are registered as resources:

superpowers://skills/brainstorming/SKILL.md
superpowers://skills/test-driven-development/testing-anti-patterns.md
superpowers://skills/systematic-debugging/root-cause-tracing.md

A resource template superpowers://skills/{skillName}/{fileName} enables dynamic access to any file.

Available Skills

Development

npm install
npm run build
npm test

Architecture

src/
  index.ts                  Entry point, stdio transport, setup and update orchestration
  server.ts                 McpServer creation, composes all registrations
  config.ts                 Persistent configuration
  update.ts                 Daily auto-update check
  git.ts                    Git operations (clone, pull, fetch) via execFile
  cli/setup.ts              Interactive setup wizard
  skills/
    types.ts                Skill, SkillFile, SkillMetadata interfaces
    discovery.ts            Directory scanning, YAML frontmatter parsing, version resolution
  tools/register.ts         list_skills, use_skill, get_skill_file
  prompts/register.ts       One MCP prompt per skill
  resources/register.ts     Static resources per file + resource template for dynamic access

Tests

Quick Start

1. Clone and build

git clone https://github.com/erophames/superpowers-mcp.git
cd superpowers-mcp
npm install
npm run build

2. Run setup

node build/index.js

On first run in a terminal, the setup wizard clones the superpowers repository and saves the configuration.

3. Configure your MCP client

Add to your client's MCP server configuration:

{
  "mcpServers": {
    "superpowers": {
      "command": "node",
      "args": ["/absolute/path/to/superpowers-mcp/build/index.js"]
    }
  }
}

Replace /absolute/path/to/ with the actual path where you cloned the repository.

Usage Examples

Once connected, ask your AI assistant:

• "What superpowers skills are available?" (calls list_skills)
• "Use the brainstorming skill to help me design a caching layer."
• "Load the TDD skill and follow it to implement this feature."
• "Read the anti-patterns file from the test-driven-development skill."
• "Recommend the best skills for implementing this MCP feature."
• "Compose a workflow for debugging flaky tests."
• "Validate this workflow: brainstorming, writing-plans, test-driven-development."
• "Search skills for root cause tracing techniques."

Configuration

Environment Variables

Skill Discovery Order

1. SUPERPOWERS_SKILLS_DIR environment variable
2. Saved directory from the setup wizard (persisted in ~/.config/superpowers-mcp)
3. Claude Code plugin cache (~/.claude/plugins/cache/claude-plugins-official/superpowers/*/skills/)

Auto-Updates

When skills are sourced from a git repository, the server checks for updates once per day on startup and pulls new changes automatically.

License

MIT