README.md•5.38 kB
# Superpowers MCP Server for Augment
An MCP (Model Context Protocol) server that brings the powerful [Superpowers](https://github.com/obra/superpowers) skills library to Augment CLI. Access proven workflows, expert techniques, and best practices directly in your AI coding assistant.
## What is This?
This MCP server exposes the Superpowers skills library as tools that Augment can use. Skills are expert-crafted workflows and processes that guide AI assistants to produce better results.
**Available Tools:**
- `find_skills` - List all available skills from both the superpowers library and your personal skills
- `use_skill` - Load a specific skill to guide your work
## Prerequisites
- **Node.js** v18 or higher ([Download](https://nodejs.org/))
- **Git** ([Download](https://git-scm.com/))
- **Augment CLI** with MCP support
## Quick Start
### 1. Clone and Install
```bash
git clone https://github.com/jmcdice/superpower-mcp.git
cd superpower-mcp
./install.sh
```
The installer will:
- Clone the upstream Superpowers repository to `~/.augment/superpowers`
- Create a personal skills directory at `~/.augment/skills`
- Install MCP server dependencies
- Provide configuration instructions
### 2. Configure Augment
Add the MCP server to your Augment configuration file (`~/.augment/settings.json`):
```json
{
"mcpServers": {
"superpowers": {
"command": "node",
"args": [
"/path/to/superpower-mcp/superpowers-mcp.js"
]
}
}
}
```
**Note:** Replace `/path/to/superpower-mcp/` with the actual path where you cloned this repository. The installer will show you the exact path to use.
### 3. Restart Augment
Restart Augment to load the new MCP server.
### 4. Test It
Ask Augment:
```
"What skills are available?"
```
You should see a list of skills from the Superpowers library.
## Usage
### Finding Skills
Ask Augment to list available skills:
```
"Show me available skills"
"What skills can you use?"
```
Or use the tool directly:
```
find_skills()
```
### Using Skills
Load a skill by name:
```
"Use the brainstorming skill"
"Load the test-driven-development skill"
```
Or use the tool directly:
```
use_skill("superpowers:brainstorming")
use_skill("superpowers:test-driven-development")
```
### Skill Naming Convention
- **Superpowers skills**: `superpowers:skill-name` (from the upstream repository)
- **Personal skills**: `my-skill-name` (from `~/.augment/skills/`)
Personal skills with the same name as superpowers skills will override them.
## Creating Personal Skills
1. Create a directory in `~/.augment/skills/` with your skill name:
```bash
mkdir -p ~/.augment/skills/my-custom-skill
```
2. Add a `SKILL.md` file with YAML frontmatter:
```markdown
---
name: my-custom-skill
description: Use when you need to do something specific
---
# My Custom Skill
## Purpose
[Describe what this skill does]
## When to Use
[Describe when to use this skill]
## Process
1. [Step 1]
2. [Step 2]
3. [Step 3]
```
3. The skill will automatically be available through `find_skills` and `use_skill`
## Architecture
This is an overlay approach that works with the upstream Superpowers repository:
- **Upstream repository**: `~/.augment/superpowers` (read-only, updated via git pull)
- **MCP server**: This repository (custom Augment integration)
- **Personal skills**: `~/.augment/skills` (your custom skills)
The MCP server reads skills from both the upstream repository and your personal skills directory.
## Management
### Update Superpowers
To get the latest skills from the upstream repository:
```bash
./install.sh update
```
Then restart Augment.
### Uninstall
```bash
./install.sh remove
```
This will:
- Remove the Superpowers repository (`~/.augment/superpowers`)
- Optionally remove your personal skills (`~/.augment/skills`)
- Keep the MCP server files (you can delete them manually if desired)
Don't forget to remove the MCP server configuration from `~/.augment/settings.json` and restart Augment.
## Troubleshooting
### MCP Server Not Showing Up
1. Check that the path in `~/.augment/settings.json` is correct
2. Verify Node.js is installed: `node --version` (should be v18+)
3. Check that dependencies are installed: `ls node_modules` in the repo directory
4. Restart Augment completely
### Skills Not Loading
1. Verify the Superpowers repository exists: `ls ~/.augment/superpowers/skills`
2. Run `./install.sh update` to refresh the repository
3. Check skill file format (must have YAML frontmatter and be named `SKILL.md`)
### Permission Errors
Make sure the install script is executable:
```bash
chmod +x install.sh
```
## Links
- **Superpowers Repository**: https://github.com/obra/superpowers
- **Blog Post**: [Superpowers for Claude Code](https://blog.fsck.com/2025/10/09/superpowers/)
- **Model Context Protocol**: https://modelcontextprotocol.io/
- **Augment**: https://www.augmentcode.com/
## Contributing
Issues and pull requests are welcome\! This is a community project to make Superpowers accessible to Augment users.
## License
MIT License - See LICENSE file for details
The upstream Superpowers repository has its own license. Please refer to https://github.com/obra/superpowers for details.
## Credits
- **Superpowers** by [Jesse Vincent](https://github.com/obra)
- **MCP Server** integration for Augment