docs: add Claude Desktop + GitHub MCP integration guide
Enable BMAD usage directly in Claude Desktop without local installation: - docs/how-to/installation/claude-desktop-github.md: Full setup guide - resources/prompts/claude-desktop-po-bootstrap.md: Copy-paste bootstrap prompts The key insight: with GitHub MCP, Claude Desktop can fetch agent definitions directly from the repo and embody them dynamically. Also enhanced PO agent setup-github prompt to cover both Claude Desktop and Claude Code workflows.
This commit is contained in:
Jonah Schulte
parent
4522c8928d
commit
e3b6029496
|
|
@ -0,0 +1,212 @@
|
|||
---
|
||||
title: "Using BMAD with Claude Desktop + GitHub"
|
||||
description: Use BMAD agents in Claude Desktop without local installation
|
||||
---
|
||||
|
||||
Use BMAD agents directly in Claude Desktop by reading agent files from GitHub. Perfect for Product Owners, stakeholders, and team members who don't need a full local development setup.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Claude Desktop** with GitHub MCP configured
|
||||
- **GitHub repository** with BMAD installed (has `_bmad/` folder)
|
||||
- **GitHub Personal Access Token** with `repo` and `issues` scopes
|
||||
|
||||
## Step 1: Configure GitHub MCP
|
||||
|
||||
Open Claude Desktop settings and add the GitHub MCP server:
|
||||
|
||||
1. Go to **Settings** → **Developer** → **Model Context Protocol**
|
||||
2. Add this configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-github"],
|
||||
"env": {
|
||||
"GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Create a token at: https://github.com/settings/tokens
|
||||
- Required scopes: `repo`, `issues`, `read:org`
|
||||
4. Restart Claude Desktop
|
||||
|
||||
## Step 2: Load a BMAD Agent
|
||||
|
||||
In a new Claude Desktop conversation, ask Claude to load an agent from your repo:
|
||||
|
||||
```
|
||||
Please read and embody the Product Owner agent from my repository.
|
||||
Fetch the file from: github.com/YOUR-ORG/YOUR-REPO at path
|
||||
src/modules/bmm/agents/po.agent.yaml
|
||||
|
||||
After reading it, introduce yourself and show me the available commands.
|
||||
```
|
||||
|
||||
Claude will:
|
||||
1. Use `mcp__github__get_file_contents` to fetch the agent definition
|
||||
2. Parse the persona, menu, and prompts
|
||||
3. Embody the agent and present the menu
|
||||
|
||||
## Step 3: Start Using Team Features
|
||||
|
||||
Once the agent is loaded, you can use all the team collaboration features:
|
||||
|
||||
### Check Your Tasks
|
||||
```
|
||||
What needs my attention?
|
||||
```
|
||||
or just type `MT`
|
||||
|
||||
### Create a PRD
|
||||
```
|
||||
Create a new PRD for user authentication
|
||||
```
|
||||
or type `CP`
|
||||
|
||||
### View PRD Dashboard
|
||||
```
|
||||
Show me all PRDs
|
||||
```
|
||||
or type `PD`
|
||||
|
||||
## Available Agents
|
||||
|
||||
| Agent | Path | Purpose |
|
||||
|-------|------|---------|
|
||||
| **Product Owner** | `src/modules/bmm/agents/po.agent.yaml` | PRD management, stories, stakeholder coordination |
|
||||
| **Analyst** | `src/modules/bmm/agents/analyst.agent.yaml` | Project initialization, workflow guidance |
|
||||
| **PM** | `src/modules/bmm/agents/pm.agent.yaml` | Requirements, epics, story creation |
|
||||
| **Architect** | `src/modules/bmm/agents/architect.agent.yaml` | Architecture decisions, technical design |
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ CLAUDE DESKTOP │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ User: "Load the PO agent from my repo" │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────┐ │
|
||||
│ │ GitHub MCP │ │
|
||||
│ │ mcp__github__get_file_contents │ │
|
||||
│ │ → Fetches po.agent.yaml │ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ Claude embodies the agent persona │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ User: "MT" (my tasks) │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────┐ │
|
||||
│ │ GitHub MCP │ │
|
||||
│ │ mcp__github__search_issues │ │
|
||||
│ │ → Finds PRDs needing attention │ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Tips for Best Results
|
||||
|
||||
### Start Each Session Fresh
|
||||
Load the agent at the beginning of each conversation:
|
||||
```
|
||||
Load the PO agent from github.com/myorg/myrepo
|
||||
```
|
||||
|
||||
### Use Natural Language
|
||||
The agent understands natural language, not just commands:
|
||||
- "What PRDs are waiting for feedback?"
|
||||
- "Create a story for the login epic"
|
||||
- "Who's working on authentication?"
|
||||
|
||||
### Combine with Project Knowledge
|
||||
For even better context, you can also upload the `llms-full.txt` file to your Claude Project:
|
||||
```
|
||||
curl https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
|
||||
```
|
||||
|
||||
This gives Claude the full BMAD methodology documentation.
|
||||
|
||||
## Comparison: Local Install vs GitHub MCP
|
||||
|
||||
| Feature | Local Install | GitHub MCP Only |
|
||||
|---------|--------------|-----------------|
|
||||
| Requires Node.js | ✅ Yes | ❌ No |
|
||||
| `/agent-name` commands | ✅ Yes | ❌ Manual load |
|
||||
| Agent files | Local in `_bmad/` | Fetched from GitHub |
|
||||
| GitHub Issues | ✅ Works | ✅ Works |
|
||||
| PRD Crowdsourcing | ✅ Works | ✅ Works |
|
||||
| Story Locking | ✅ Works | ✅ Works |
|
||||
| Best for | Developers | POs, Stakeholders |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Agent file not found"
|
||||
- Verify the repository has BMAD installed
|
||||
- Check the file path is correct
|
||||
- Ensure your token has `repo` access
|
||||
|
||||
### "GitHub API errors"
|
||||
- Check your token hasn't expired
|
||||
- Verify the token has required scopes
|
||||
- Try: "Can you call mcp__github__get_me?"
|
||||
|
||||
### "Agent doesn't understand commands"
|
||||
- Make sure Claude fully read and embodied the agent
|
||||
- Try asking Claude to "show the menu" to verify
|
||||
- Start a fresh conversation and reload the agent
|
||||
|
||||
## Quick Start - Bootstrap Prompts
|
||||
|
||||
Copy and paste this into Claude Desktop to get started immediately:
|
||||
|
||||
### Minimal Version
|
||||
```
|
||||
Load the Product Owner agent from github.com/YOUR-ORG/YOUR-REPO
|
||||
(path: src/modules/bmm/agents/po.agent.yaml) and enter PO mode.
|
||||
Show me what needs my attention.
|
||||
```
|
||||
|
||||
### Full Version
|
||||
```
|
||||
Fetch and embody the BMAD Product Owner agent.
|
||||
|
||||
1. Read the agent definition from GitHub:
|
||||
- Repository: YOUR-ORG/YOUR-REPO
|
||||
- Path: src/modules/bmm/agents/po.agent.yaml
|
||||
|
||||
2. After reading, fully embody this agent:
|
||||
- Adopt the persona (name, role, communication style)
|
||||
- Internalize all principles
|
||||
- Make the menu commands available
|
||||
|
||||
3. Introduce yourself and show the available commands.
|
||||
|
||||
4. Then check: what PRDs or stories need my attention?
|
||||
|
||||
Use GitHub MCP tools (mcp__github__*) for all GitHub operations.
|
||||
```
|
||||
|
||||
Replace `YOUR-ORG` and `YOUR-REPO` with your actual repository details.
|
||||
|
||||
For more bootstrap prompts (including stakeholder-specific versions), see:
|
||||
`resources/prompts/claude-desktop-po-bootstrap.md`
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- [Install BMAD Locally](./install-bmad.md) - Full local installation
|
||||
- [Team Collaboration Features](../../../docs/TEAM-COLLABORATION-FEATURES.md) - PRD crowdsourcing overview
|
||||
- [Getting Started](../../tutorials/getting-started/getting-started-bmadv6.md) - Full tutorial
|
||||
|
|
@ -0,0 +1,98 @@
|
|||
# BMAD Product Owner - Claude Desktop Bootstrap
|
||||
|
||||
Copy and paste this entire prompt into Claude Desktop to activate the Product Owner agent.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start (Replace YOUR-ORG/YOUR-REPO)
|
||||
|
||||
```
|
||||
Fetch and embody the BMAD Product Owner agent.
|
||||
|
||||
1. Read the agent definition from GitHub:
|
||||
- Repository: YOUR-ORG/YOUR-REPO
|
||||
- Path: src/modules/bmm/agents/po.agent.yaml
|
||||
|
||||
2. After reading, fully embody this agent:
|
||||
- Adopt the persona (name, role, communication style)
|
||||
- Internalize all principles
|
||||
- Make the menu commands available
|
||||
- Load any prompts defined in the file
|
||||
|
||||
3. Introduce yourself and show the available commands.
|
||||
|
||||
4. Then check: what PRDs or stories need my attention?
|
||||
|
||||
Use GitHub MCP tools (mcp__github__*) for all GitHub operations.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example with Real Repository
|
||||
|
||||
```
|
||||
Fetch and embody the BMAD Product Owner agent.
|
||||
|
||||
1. Read the agent definition from GitHub:
|
||||
- Repository: acme-corp/acme-platform
|
||||
- Path: src/modules/bmm/agents/po.agent.yaml
|
||||
|
||||
2. After reading, fully embody this agent:
|
||||
- Adopt the persona (name, role, communication style)
|
||||
- Internalize all principles
|
||||
- Make the menu commands available
|
||||
- Load any prompts defined in the file
|
||||
|
||||
3. Introduce yourself and show the available commands.
|
||||
|
||||
4. Then check: what PRDs or stories need my attention?
|
||||
|
||||
Use GitHub MCP tools (mcp__github__*) for all GitHub operations.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Minimal Version
|
||||
|
||||
If you just want the shortest possible bootstrap:
|
||||
|
||||
```
|
||||
Load the Product Owner agent from github.com/YOUR-ORG/YOUR-REPO
|
||||
(path: src/modules/bmm/agents/po.agent.yaml) and enter PO mode.
|
||||
Show me what needs my attention.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## For Stakeholders (Non-PO Team Members)
|
||||
|
||||
Stakeholders who just need to give feedback on PRDs can use a lighter prompt:
|
||||
|
||||
```
|
||||
I'm a stakeholder who needs to review PRDs and give feedback.
|
||||
|
||||
Load the Product Owner agent from github.com/YOUR-ORG/YOUR-REPO
|
||||
(path: src/modules/bmm/agents/po.agent.yaml)
|
||||
|
||||
Then show me:
|
||||
1. What PRDs need my feedback
|
||||
2. What PRDs need my sign-off
|
||||
|
||||
I'll mainly use these commands:
|
||||
- MT (my tasks)
|
||||
- SF (submit feedback)
|
||||
- SO (sign off)
|
||||
- VF (view feedback)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before using these prompts, ensure:
|
||||
|
||||
1. **GitHub MCP is configured** in Claude Desktop settings
|
||||
2. **Your repo has BMAD installed** (has `src/modules/bmm/agents/` folder)
|
||||
3. **Your GitHub token** has `repo` and `issues` scopes
|
||||
|
||||
See the full setup guide: `docs/how-to/installation/claude-desktop-github.md`
|
||||
|
|
@ -193,15 +193,23 @@ agent:
|
|||
|
||||
This guide helps you enable team collaboration features.
|
||||
|
||||
## Step 1: Verify GitHub MCP
|
||||
## Are You Using Claude Desktop or Claude Code?
|
||||
|
||||
Claude Desktop needs the GitHub MCP server to interact with GitHub Issues.
|
||||
**Claude Desktop (chat app):**
|
||||
- You only need GitHub MCP configured
|
||||
- I can read agent files directly from your GitHub repo
|
||||
- No local BMAD installation required!
|
||||
|
||||
**Check if configured:**
|
||||
I'll try to call the GitHub API. If this fails, you need to set up GitHub MCP.
|
||||
**Claude Code (CLI tool):**
|
||||
- Run `npx bmad-method install` in your project
|
||||
- Then configure GitHub MCP for team features
|
||||
|
||||
## Step 1: Configure GitHub MCP
|
||||
|
||||
Both Claude Desktop and Claude Code need GitHub MCP for team features.
|
||||
|
||||
**To add GitHub MCP:**
|
||||
1. Open Claude Desktop Settings (Cmd/Ctrl + ,)
|
||||
1. Open Settings (Cmd/Ctrl + ,)
|
||||
2. Go to "Developer" → "Model Context Protocol"
|
||||
3. Add the GitHub MCP server:
|
||||
```json
|
||||
|
|
@ -219,9 +227,19 @@ agent:
|
|||
```
|
||||
4. Create a GitHub token at: https://github.com/settings/tokens
|
||||
- Required scopes: `repo`, `issues`, `read:org`
|
||||
5. Restart Claude Desktop
|
||||
5. Restart Claude
|
||||
|
||||
## Step 2: Enable GitHub Integration in BMAD
|
||||
## Step 2: For Claude Desktop Users (No Local Install)
|
||||
|
||||
I can load myself directly from your GitHub repo! Just tell me:
|
||||
```
|
||||
Load the PO agent from github.com/YOUR-ORG/YOUR-REPO
|
||||
at path: src/modules/bmm/agents/po.agent.yaml
|
||||
```
|
||||
|
||||
Then I'll fetch my full definition and embody the agent persona.
|
||||
|
||||
## Step 3: For Claude Code Users (Local Install)
|
||||
|
||||
Edit `_bmad/bmm/config.yaml`:
|
||||
|
||||
|
|
@ -232,7 +250,7 @@ agent:
|
|||
repo: "your-repo-name"
|
||||
```
|
||||
|
||||
## Step 3: Configure Notifications (Optional)
|
||||
## Step 4: Configure Notifications (Optional)
|
||||
|
||||
For Slack notifications, add to config.yaml:
|
||||
```yaml
|
||||
|
|
@ -243,7 +261,7 @@ agent:
|
|||
channel: "#prd-updates"
|
||||
```
|
||||
|
||||
## Step 4: Verify Setup
|
||||
## Step 5: Verify Setup
|
||||
|
||||
Say "my tasks" or `MT` to verify everything works.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue