Spec Workflow MCP Server

How to use

Use this MCP server to manage spec-driven workflows from your preferred interface. You can start a dashboard for real-time monitoring or connect via a client (CLI or IDE) to perform actions like creating specs, listing specs, and executing tasks. The dashboard provides live updates on specs, tasks, and progress, while the VSCode extension offers an embedded experience inside your editor.

How to install

Prerequisites: Node.js and npm installed on your system. You may also use a client like Claude, Cline/Claude Dev, Continue IDE, Cursor IDE, OpenCode, Windsurf, or Codex if you want to configure MCP connections in those environments.

1) Add the MCP server to your client configuration using the following snippet.

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

Additional sections

Dashboard start options and a quick-start workflow are provided to help you begin quickly.

3) Start the web dashboard (recommended for CLI users):

npx -y @pimzino/spec-workflow-mcp@latest --dashboard
```

The dashboard runs on port 5000 by default and is accessible at http://localhost:5000. Only one dashboard instance is needed, and all projects connect to the same dashboard.

Configuration and security notes

You can also run the MCP server using local configurations for various environments. For local development and sandboxed setups, you might set an environment variable to redirect global state files.

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace
`

Docker deployment

Run the dashboard in a container for isolated deployment.

# Using Docker Compose (recommended)
cd containers
docker-compose up --build

# Or using Docker CLI
docker build -f containers/Dockerfile -t spec-workflow-mcp .
docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp
```

The dashboard will be available at http://localhost:5000.

Notes on usage with editors and IDEs

Install the VSCode extension Spec Workflow MCP for an integrated sidebar dashboard inside VSCode. You can also mention spec-workflow in conversations to trigger actions like creating a spec, listing specs, or executing tasks.

Security

The server includes security controls such as localhost binding by default, rate limiting, audit logging, security headers, and protected origins. For external access, use a reverse proxy with TLS and authentication.

Sandboxed environments

In sandboxed environments where HOME is read-only, redirect global state files using SPEC_WORKFLOW_HOME as shown above.

Dashboard

Real-time web dashboard for monitoring specs, tasks, and progress with live updates.

VSCode Extension

Integrated sidebar dashboard inside VSCode for seamless workflow management.

Approval Workflow

Supports the full approval process with revisions and feedback.

Task Progress Tracking

Visual progress indicators and detailed task statuses.

Implementation Logs

Searchable logs of all task implementations with code statistics.

Multi-Language Support

Available in 11 languages for broader accessibility.