Spec Driver MCP is a Model Context Protocol server that enables structured, spec-driven AI development by guiding projects through a 3-phase workflow (Requirements → Design → Tasks) with approval gates and automation hooks.
Initialize a spec workspace (init-spec): Set up a .spec/ directory with config, default hooks, and support for feature or bugfix spec types using requirements-first or design-first workflows.
Write spec documents (write-spec-file): Create or update the three core spec files:
requirements.md — User stories and acceptance criteria
design.md — Architecture, components, and data flow
tasks.md — Trackable checkbox task lists
Read spec documents (read-spec-file): Retrieve the current content of any core spec file.
List spec files (list-spec-files): View the status of all spec files, including existence, size, task counts, and associated hooks.
Track task progress (update-task): Mark individual tasks as completed [x] or pending [ ] in tasks.md, identified by line number or partial text match.
Get task summary (get-task-summary): Retrieve overall task completion statistics (completed vs. total tasks).
Create automation hooks (create-hook): Register event-driven rules that instruct the AI to automatically perform actions when specific workflow events occur (e.g., auto-mark tasks, validate phase transitions, sync docs on requirement changes).
List hooks (list-hooks): View all registered automation hooks, their trigger events, and descriptions.
Delete hooks (delete-hook): Remove a specific automation hook by name.
Run hooks (run-hooks): Execute all hooks associated with a specific event (e.g., on-task-completed, on-spec-phase-change), enabling automated workflow enforcement at key development milestones.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@spec-driver-mcp analyze my project and create a spec"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that brings Kiro-style spec-driven development to any AI coding tool (Claude Code, Cursor, opencode, Codex CLI, Reasonix, Gemini CLI, and more).
Replaces unstructured chat with a 3-phase workflow when you ask AI to build, plan, or refactor a project:
Phase 1: Requirements → requirements.md (EARS format: WHEN...THE SYSTEM SHALL...)
Phase 2: Design → design.md (architecture, components, data flow)
Phase 3: Tasks → tasks.md (trackable [x] checkboxes)Each phase requires your approval before advancing. Hooks auto-maintain consistency.
Related MCP server: Pathfinder MCP Server
npx github:linanwanttodo/spec-driver-mcpOr install globally:
npm install -g github:linanwanttodo/spec-driver-mcpAdd to ~/.config/opencode/opencode.json:
{
"mcp": {
"spec-driver": {
"type": "local",
"command": ["npx", "github:linanwanttodo/spec-driver-mcp"]
}
}
}Add to ~/.claude/settings.json:
{
"mcpServers": {
"spec-driver": {
"command": "npx",
"args": ["github:linanwanttodo/spec-driver-mcp"]
}
}
}Then copy instructions/CLAUDE.md to your project root as CLAUDE.md.
Create .cursor/mcp.json in your project:
{
"mcpServers": {
"spec-driver": {
"command": "npx",
"args": ["github:linanwanttodo/spec-driver-mcp"]
}
}
}Then copy instructions/cursor-rules.md to your project root as .cursorrules.
Add to ~/.codex/config.toml:
[mcp_servers.spec-driver]
command = "npx"
args = ["github:linanwanttodo/spec-driver-mcp"]Add to ~/.reasonix/config.json mcp array:
"spec-driver=npx github:linanwanttodo/spec-driver-mcp"Add to ~/.gemini/config/mcp_config.json:
{
"mcpServers": {
"spec-driver": {
"command": "npx",
"args": ["github:linanwanttodo/spec-driver-mcp"]
}
}
}Once configured, just tell your AI:
"帮我开发一个博客系统" or "帮我分析这个项目" or "我们来重构这个"
The AI will automatically:
Read your codebase to understand context
Ask you clarifying questions (requirements-first or design-first? specific details?)
Write requirements.md using EARS notation
Wait for your approval before proceeding
Write design.md with architecture and component design
Wait for your approval
Write tasks.md with - [ ] checkboxes
Wait for your approval, then implement
During implementation:
- [x] Task completed via update-task
- [ ] Still pendingThe AI auto-runs hooks at each event:
on-task-completed → auto-mark task [x], check acceptance criteria
on-spec-phase-change → validate document completeness
on-user-request-change → sync all documents
Tool | Description |
| Initialize .spec/ with config + 3 default hooks |
| Write requirements.md / design.md / tasks.md |
| Read any spec file |
| Show file status + hooks |
| Toggle task [x] or [ ] |
| Task completion stats |
| Create automation rules |
| List all hooks |
| Remove a hook |
| Execute hooks for an event |
All files are created in .spec/ at your project root:
your-project/
├── .spec/
│ ├── .config # Project metadata
│ ├── requirements.md # Phase 1: Requirements
│ ├── design.md # Phase 2: Design
│ ├── tasks.md # Phase 3: Tasks
│ └── hooks/ # Automation rules
│ ├── auto-mark-completed.md
│ ├── validate-before-phase.md
│ └── notify-on-change.md
├── ...your code...Hook | Event | What it does |
|
| Auto update-task after implementation |
|
| Validate doc completeness before advancing |
|
| Sync all docs when requirements change |
If you're asking an AI to set this up for you, copy this:
Install spec-driver-mcp from GitHub and configure it:
1. Run: npm install -g github:linanwanttodo/spec-driver-mcp
2. Add "spec-driver" to the MCP servers config of my AI tool
(the config format depends on which tool I use)
3. Done - no server needed, no API keys, no registrationMIT
Register an automation hook for the spec workflow. Hooks define actions the AI should automatically perform when specific events occur. Events: on-requirements-confirmed, on-design-confirmed, on-tasks-confirmed, on-task-completed, on-implementation-done, on-spec-phase-change, on-user-request-change, manual
Example: when a task is completed (on-task-completed), auto-run update-task to mark it [x].
Inputs: name (required), event (required), description (required), instructions (required).
Remove a hook by name.
Inputs: name (required).
Get a summary of task completion status from tasks.md.
Inputs: no named parameters.
Initialize a spec-driven development workspace for the current project. Creates a .spec/ directory that will hold three files:
requirements.md: User stories, acceptance criteria (EARS format)
design.md: Architecture, diagrams, implementation approach
tasks.md: Trackable checkbox tasks
hooks/: Event-driven automation rules
Call this FIRST when user expresses intent to build, plan, design, analyze, or refactor.
Inputs: projectName (required), specType, workflowType.
List all registered hooks with their event type and description. Use this to review what automations are active.
Inputs: no named parameters.
List all spec files with their status (exists, size, task count).
Inputs: no named parameters.
Read the content of one of the three spec files. Use this to review requirements, check design decisions, or see task status.
Inputs: file (required).
Get all hooks matching a specific event type. The AI should call this when an event occurs and execute the matching hooks' instructions. For example, after completing implementation of a task, call run-hooks with event "on-task-completed" to find and execute all relevant hooks.
Inputs: event (required).
Mark a task as done or pending in tasks.md. Use this during implementation to track progress. The task is identified by matching its text content (case-insensitive partial match).
Inputs: done (required), match, line.
Write content to one of the three spec files. Use this to create or update requirements.md, design.md, or tasks.md.
Inputs: file (required), content (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Each tool has a clearly distinct purpose: hooks management (create/delete/list/run), spec file operations (init/read/write/list), and task tracking (get-task-summary/update-task). No overlap or ambiguity.
All tool names follow a consistent pattern of verb-noun (or verb-object) using lowercase with hyphens, e.g., 'create-hook', 'init-spec', 'update-task'. No mixing of conventions.
With 10 tools, the set is well-scoped for a spec-driven development workflow. It covers every necessary operation without being excessive or insufficient.
The tool surface covers the full lifecycle: initialization, file management, task tracking, and automation hooks. No obvious missing operations for the stated purpose.
Turn PRDs and product ideas into structured specs so coding agents build your intent, not theirs.
Design spec + milestones AI coding agents read before building; drift flagged, changes reviewed.
Work management with Spec-Driven Development: tasks, sprints and SDD approvals for coding agents.
AI-powered spec-to-task decomposition and execution orchestration for coding agents.
