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

Client	Config Location
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code	~/.claude.json or project .mcp.json
Cursor	Cursor Settings > MCP
Windsurf	~/.codeium/windsurf/mcp_config.json

What It Exposes

The server registers skills through all three MCP primitives:

Tools

Tool	Description
list_skills	List all available skills with descriptions and file lists
use_skill	Load a skill by name -- returns the full skill content as instructions to follow (optional guardrail enforcement)
get_skill_file	Load a supporting file from a skill (reference docs, prompt templates, scripts)
recommend_skills	Recommend top skills for a task using semantic ranking + workflow policy boosts
compose_workflow	Build an ordered multi-skill workflow for a goal
validate_workflow	Validate selected skills against required workflow guardrails
semantic_search_skills	Semantic search across SKILL.md and supporting files

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

Skill	What it does
brainstorming	Collaborative design through questions, approaches, and incremental validation
writing-plans	Bite-sized implementation plans with exact file paths and TDD steps
executing-plans	Batch execution of plans with review checkpoints between tasks
subagent-driven-development	Fresh subagent per task with two-stage code review
dispatching-parallel-agents	Distribute independent tasks to concurrent agents
test-driven-development	RED-GREEN-REFACTOR cycle -- write failing test first, always
systematic-debugging	4-phase root cause analysis: investigate before you fix
verification-before-completion	Run the command, read the output, then claim the result
requesting-code-review	Dispatch code review and act on severity-categorized feedback
receiving-code-review	Technical rigor when receiving feedback -- verify, don't blindly agree
using-git-worktrees	Isolated git worktrees for parallel feature development
finishing-a-development-branch	Structured options for merge, PR, or cleanup when done
writing-skills	Framework for creating, testing, and deploying new skills
using-superpowers	How the skill system works and when to invoke 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

Variable	Description
SUPERPOWERS_SKILLS_DIR	Override the skills directory path directly

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

Script	Description
npm run build	Compile TypeScript
npm run dev	Watch mode compilation
npm test	Run all 58 tests
npm run test:watch	Watch mode tests
npm start	Run the server

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