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
• Task Tracking: Parse tasks.md and track progress in real-time
• Approval Workflow: Request, approve, and reject change proposals
• Web Dashboard: Visual management interface with real-time updates

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 Tools

Guides

Management

Validation

Archive

Tasks

Approval

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)
  -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 updates
• Task Management: Toggle task status directly from the UI
• Approval Actions: Approve/reject changes with comments
• Progress Visualization: Progress bars and status badges

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