OpenSpec

OpenSpec MCP is a server that exposes OpenSpec’s capabilities as an MCP service. It lets you run the OpenSpec MCP locally or with a dashboard, track changes and tasks in real time, and manage approvals for changes all from a single, repeatable workflow.

How to use

You interact with the OpenSpec MCP server through an MCP client. Add the OpenSpec MCP server to your MCP configuration, then start it with or without the web dashboard. From your chat or command interface you can list changes, view details, update task status, and request or manage approvals. The dashboard provides a live view of progress, changes, and approvals and updates in real time via WebSocket.

How to install

Prerequisites you need before starting: Node.js version 20 or higher.

Install and run the OpenSpec MCP server using the recommended Claude Code CLI commands, or configure it directly in your MCP config. Choose the approach that fits your workflow.

# Add the OpenSpec MCP server to your MCP configuration (recommended via Claude Code CLI)
claude mcp add openspec -- npx openspec-mcp

# Add with the dashboard
claude mcp add openspec -- npx openspec-mcp --with-dashboard

# Add for a specific project path
claude mcp add openspec -- npx openspec-mcp /path/to/your/project

# JSON-based configuration (simple stdio config without dashboard)
{
  "mcpServers": {
    "openspec": {
      "command": "npx",
      "args": ["-y", "openspec-mcp"]
    }
  }
}

# JSON-based configuration (with dashboard)
{
  "mcpServers": {
    "openspec": {
      "command": "npx",
      "args": ["-y", "openspec-mcp", "--with-dashboard"]
    }
  }
}

How the server is configured

The server is configured to run the OpenSpec MCP process via a standard Node-based runtime. You can start the server in MCP mode with or without the web dashboard. The baseline configuration uses the OpenSpec MCP package and the npx command to launch it, enabling immediate access to task tracking, approvals, and the real-time dashboard when you include the dashboard flag.

Notes on usage and workflow

• To list all changes you can say or type: “List all openspec changes.” - To view details of a specific change, use a phrase like: “Show me the add-user-auth change.” - To update a task’s status, say: “Mark task 1.1 as done in add-user-auth.” - To initiate an approval, say: “Request approval for add-user-auth from @reviewer.” - When you start the dashboard, you get a live view of progress, tasks, and approvals with the ability to approve or reject changes directly in the UI.

Example commands you can use in conversation

List all changes: List all openspec changes

Show change: Show me the add-user-auth change

Update task: Mark task 1.1 as done in add-user-auth

Request approval: Request approval for add-user-auth from @reviewer

Web Dashboard overview

The Web Dashboard provides a visual interface to manage changes, track task progress, and handle approvals. It supports real-time updates through a WebSocket connection, allows toggling task status from the UI, and provides progress bars and status badges to give you a clear view of what’s happening.

Development and maintenance notes

To work with the server locally, install dependencies, build if needed, and run in development mode as you iterate on features. The OpenSpec MCP server relies on Node.js and the OpenSpec MCP package, so keep your tooling up to date and ensure compatibility with your project’s Node version.

Available tools

openspec_get_instructions

Get AGENTS.md usage guide

openspec_get_project_context

Get project.md context

openspec_list_changes

List all change proposals

openspec_list_specs

List all specifications

openspec_show_change

Show change details

openspec_show_spec

Show spec details

openspec_validate_change

Validate a change

openspec_validate_spec

Validate a spec

openspec_validate_all

Batch validation

openspec_archive_change

Archive completed change

openspec_get_tasks

Get tasks and progress

openspec_update_task

Update task status

openspec_get_progress_summary

Get all changes progress

openspec_get_approval_status

Get approval status

openspec_request_approval

Request approval

openspec_approve_change

Approve a change

openspec_reject_change

Reject a change

openspec_list_pending_approvals

List pending approvals