playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

Spec Workflow MCP server

Provides structured project management through a four-phase development workflow with requirements gathering, technical design, task breakdown, and implementation execution, featuring real-time web dashboard monitoring, approval workflows for stakeholder review, and specialized validation agents for systematic feature development with documentation trails and collaborative oversight.
Back to servers
Setup instructions
Provider
Pimzino
Release date
Aug 08, 2025
Language
Python
Stats
1.6K stars
View on GitHub

Spec Workflow MCP provides structured spec-driven development workflow tools for AI-assisted software development. It features a real-time web dashboard and VSCode extension that help you monitor and manage your project's progress directly in your development environment.

Installation

Quick Start

  1. Add to your AI tool configuration:

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

    With Auto-Started Dashboard:

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

    With Custom Port:

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

  2. Choose your interface:

    Option A: Web Dashboard (Required for CLI users)

    # Dashboard only mode (uses ephemeral port)
npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard

# Dashboard only with custom port
npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard --port 3000

# View all available options
npx -y @pimzino/spec-workflow-mcp@latest --help

    Command-Line Options:

    • --help - Show comprehensive usage information and examples
    • --dashboard - Run dashboard-only mode (no MCP server)
    • --AutoStartDashboard - Auto-start dashboard with MCP server
    • --port <number> - Specify dashboard port (1024-65535)
    • --config <path> - Use custom config file instead of default location

    Option B: VSCode Extension (Recommended for VSCode users)

    Install the Spec Workflow MCP Extension from the VSCode marketplace:

    1. Open VSCode in your project directory containing .spec-workflow/
    2. The extension automatically provides the dashboard functionality within VSCode
    3. Access via the Spec Workflow icon in the Activity Bar

Configuration

You can configure the server using a TOML configuration file. By default, the server looks for <project-dir>/.spec-workflow/config.toml, but you can specify a custom location using the --config flag.

Example configuration:

# Project directory (defaults to current directory)
projectDir = "/path/to/your/project"

# Dashboard port (1024-65535)
port = 3456

# Auto-start dashboard with MCP server
autoStartDashboard = true

# Run dashboard-only mode
dashboardOnly = false

# Interface language (en, ja, zh, es, pt, de, fr, ru, it, ko, ar)
lang = "en"

Using Custom Config Files:

# Use custom config file
npx @pimzino/spec-workflow-mcp --config ~/my-configs/spec.toml

# Custom config with dashboard
npx @pimzino/spec-workflow-mcp --config ./dev-config.toml --dashboard

# CLI args still override custom config
npx @pimzino/spec-workflow-mcp --config ./config.toml --port 4000

MCP Client Setup

Augment Code

Configure in your Augment settings:

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

Claude Code CLI

Add to your MCP configuration:

claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project

Alternative for Windows (if the above doesn't work):

claude mcp add spec-workflow cmd.exe /c "npx @pimzino/spec-workflow-mcp@latest /path/to/your/project"

Claude Desktop

Add to claude_desktop_config.json:

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

How to Use

You can mention spec-workflow or your configured server name in your conversation. The AI will handle the workflow automatically, or you can use these example prompts:

Creating Specs

  • "Create a spec for user authentication" - Creates complete spec workflow for that feature
  • "Create a spec called payment-system" - Builds full requirements → design → tasks
  • "Build a spec for @prd" - Takes your existing PRD and creates the complete spec workflow from it

Getting Information

  • "List my specs" - Shows all specs and their current status
  • "Show me the user-auth progress" - Displays detailed progress information

Implementation

  • "Execute task 1.2 in spec user-auth" - Runs a specific task from your spec
  • Copy prompts from dashboard - Use the "Copy Prompt" button in the task list on your dashboard

Workflow Process

1. Project Setup (Recommended)

steering-guide → create-steering-doc (product, tech, structure)

Creates foundational documents to guide your project development.

2. Feature Development

spec-workflow-guide → create-spec-doc → [review] → implementation

Sequential process: Requirements → Design → Tasks → Implementation

3. Implementation Support

  • Use get-spec-context for detailed implementation context
  • Use manage-tasks to track task completion
  • Monitor progress via the web dashboard or VSCode extension

Available Tools

Workflow Guides

  • spec-workflow-guide - Complete guide for the spec-driven workflow process
  • steering-guide - Guide for creating project steering documents

Spec Management

  • create-spec-doc - Create/update spec documents (requirements, design, tasks)
  • spec-list - List all specs with status information
  • spec-status - Get detailed status of a specific spec
  • manage-tasks - Comprehensive task management for spec implementation

Context & Templates

  • get-template-context - Get markdown templates for all document types
  • get-steering-context - Get project steering context and guidance
  • get-spec-context - Get context for a specific spec

Steering Documents

  • create-steering-doc - Create project steering documents (product, tech, structure)

Approval System

  • request-approval - Request user approval for documents
  • get-approval-status - Check approval status
  • delete-approval - Clean up completed approvals

Troubleshooting

Common Issues

  1. Claude MCP configuration not working with project path

    • Ensure you're using the correct syntax with the -- separator
    • Verify the path exists and is accessible

  2. Dashboard not starting

    • Ensure you're using the --dashboard flag
    • Check console output for the dashboard URL and any error messages

  3. Port conflicts

    • If you get a "port already in use" error, try a different port with --port <different-number>
    • Omit the --port parameter to automatically use an available ephemeral port

  4. Dashboard not updating

    • The dashboard uses WebSockets for real-time updates
    • Refresh the browser if connection is lost

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later