OpenSpec MCP

MCP (Model Context Protocol) server for OpenSpec - spec-driven development with real-time dashboard and approval workflow.

Features

• MCP Tools: Full OpenSpec CLI functionality exposed as MCP tools
• Review System: Add, reply, resolve review comments on proposals/designs
• Task Tracking: Parse tasks.md and track progress in real-time
• Approval Workflow: Request, approve, and reject change proposals
• Cross-Service Docs: View cross-service design documents from single service projects
• Web Dashboard: Visual management interface with real-time updates and Markdown rendering

Quick Start

1. Add to your MCP configuration

Claude Code CLI (recommended - uses current directory):

claude mcp add openspec -- npx openspec-mcp

Claude Code CLI with Dashboard:

claude mcp add openspec -- npx openspec-mcp --with-dashboard

Claude Code CLI with specific project path:

claude mcp add openspec -- npx openspec-mcp /path/to/your/project

Claude Desktop / Cursor / Other:

{
  "mcpServers": {
    "openspec": {
      "command": "npx",
      "args": ["-y", "openspec-mcp"]
    }
  }
}

With Dashboard:

{
  "mcpServers": {
    "openspec": {
      "command": "npx",
      "args": ["-y", "openspec-mcp", "--with-dashboard"]
    }
  }
}

2. Use in conversation

# List all changes
"List all openspec changes"

# Show change details
"Show me the add-user-auth change"

# Update task status
"Mark task 1.1 as done in add-user-auth"

# Request approval
"Request approval for add-user-auth from @reviewer"

Available Prompts (New!)

Directly leverage your Client's AI capabilities (Claude, Codex) with context-aware prompts.

Available Tools

Guides & Context

Management

Validation

Archive

Tasks

Approval

Reviews

Templates

Generator

Hooks

Cross-Service

Cross-Service Documentation

For multi-service projects sharing a common .cross-service/ directory (e.g., in a Git worktree), configure your proposal.md frontmatter:

---
crossService:
  rootPath: "../../../../.cross-service" # Relative to change directory
  documents:
    - design.md
    - flows.md
    - services.yaml
  archivePolicy: snapshot # 'snapshot' (default) or 'reference'
---
# Your proposal content...

The Dashboard will display a "Cross-Service" tab with:

• design.md / flows.md: Rendered as Markdown
• services.yaml: Visual card view with service status, changes, and deployment order

Approval Workflow

draft -> pending_approval -> approved -> implementing -> completed -> archived
                         -> rejected -> draft (revise and resubmit)

Approval records are stored in openspec/approvals/<change-id>.json.

CLI Options

openspec-mcp [path] [options]

Arguments:
  path                    Project directory path (default: current directory)

Options:
  --dashboard             Start web dashboard only (HTTP mode)
  --with-dashboard        Start MCP server with web dashboard
  -p, --port <number>     Dashboard port (default: 3000; auto-increments if busy, 0 for random)
  -V, --version           Output version number
  -h, --help              Display help

Examples

# MCP server only (uses current directory)
openspec-mcp

# MCP server with specific project
openspec-mcp /path/to/project

# Dashboard only
openspec-mcp --dashboard

# MCP server + Dashboard
openspec-mcp --with-dashboard

# Dashboard on custom port
openspec-mcp --dashboard --port 8080

Web Dashboard

The dashboard provides a visual interface for managing changes, tracking tasks, and handling approvals.

Dashboard Pages

Features

• Real-time Updates: WebSocket connection for live progress and review updates
• Kanban Board: 6-column workflow (Backlog -> Released) with drag-and-drop support
• QA Dashboard: Monitor and trigger quality checks directly from UI
• Context Analysis: Auto-detect tech stack and visualize directory structure
• Task Management: Toggle task status directly from the UI
• Approval Actions: Approve/reject changes with comments
• Progress Visualization: Progress bars and status badges
• Review Management: View, resolve and track reviews with Open/Resolved tabs
• Cross-Service Docs: View cross-service design documents with visual services.yaml display
• Markdown Rendering: Proposals and designs rendered with full Markdown support

Development

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Run tests
npm test

Requirements

• Node.js >= 20.0.0
• OpenSpec CLI (npm install -g @fission-ai/openspec)

License

MIT