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.

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.

Client-specific config file locations

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

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.

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

License

MIT