MCP setup — SpecDrive

How MCP mode works

SpecDrive MCP scans your repo and returns generation bundles (prompts + context). You (Cursor/Claude) generate the markdown using your host API key, then call write_spec_document. SpecDrive never calls an LLM in MCP mode.

Install (one command)

cd your-app
npx -y @specdrive/mcp setup --stack flutter

Writes .specdrive/mcp.json + IDE config. Reload MCP in your editor.

npx -y @specdrive/mcp shows a waiting message?

Installed correctly. MCP uses stdio — the server waits for your IDE. Test via chat (search_specs), not the terminal.

Any MCP client

Same server everywhere — only the config file path changes:

Client	Config
Cursor, Windsurf	`.cursor/mcp.json`
Claude Desktop	`claude_desktop_config.json` (absolute `cwd`)
Cline, Continue, other	Project `.specdrive/mcp.json` or client-specific MCP settings

{
  "mcpServers": {
    "specdrive": {
      "command": "npx",
      "args": ["-y", "@specdrive/mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Claude Desktop: replace cwd with /absolute/path/to/your/project.

Cursor extras

spec setup cursor --stack flutter

Adds workflow rules + specdrive-sdd skill on top of MCP.

Install (manual)

npm install -g @specdrive/mcp @specdrive/cli
# Or: npx -y @specdrive/mcp  (test only — IDE starts MCP automatically)

Run spec setup mcp in your project before using MCP tools.

Cursor (legacy manual)

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "specdrive": {
      "command": "npx",
      "args": ["-y", "@specdrive/mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

Restart Cursor or reload MCP servers from settings.

Claude Desktop

Edit claude_desktop_config.json:

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

{
  "mcpServers": {
    "specdrive": {
      "command": "npx",
      "args": ["-y", "@specdrive/mcp"],
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

Replace cwd with your project root. Restart Claude Desktop.

Global install alternative

npm install -g @specdrive/mcp

{
  "mcpServers": {
    "specdrive": {
      "command": "specdrive-mcp",
      "cwd": "/absolute/path/to/your/project"
    }
  }
}

MCP workflow (Kiro-style)

Human gates — never auto-approve

After every write_spec_document, the host AI must show you the full document and STOP. Only call update_spec with userConfirmed: true after you reply approve / request changes / reject.

create_spec → YOUR JOURNEY + brief bundle 1 brief → write → STOP → you approve 2 requirements → write → STOP → approve 3 generate_gap_analysis → write → STOP → approve 4 generate_design_hld → write → STOP → approve 5 generate_design_lld → write → STOP → approve 6 generate_tasks → write → STOP → approve (last human gate) 7 get_next_task → implement (Design2Code only if user wants Figma on a UI task) 8 review_code → validate

Works in any repo — edit .specdrive/steering/ so paths match your packages.

Figma + Design2Code (figma-to-code)

SpecDrive MCP can call your Design2Code integration for UI tasks only. State, BLoC, navigation, validation, and tests stay with Cursor/Claude via get_next_task.

Figma token (Personal Access Token)

Figma does not use OAuth popups like GitHub. You generate a token once:

Open figma.com/settings
Scroll to Personal access tokens
Generate → copy token (starts with figd_)

# Option A — Design2Code config (recommended)
design2code login --figma-token figd_YOUR_TOKEN

# Option B — shell profile
export FIGMA_TOKEN="figd_YOUR_TOKEN" >> ~/.zshrc

# Option C — Cursor MCP env
"env": { "FIGMA_TOKEN": "figd_YOUR_TOKEN" }

Link Figma file to project

# .specdrive/figma.json
{
  "fileKey": "YOUR_FIGMA_FILE_KEY"
}

Auto-run UI tasks (ask token at task time)

# MCP get_next_task on UI task → asks user for Figma token or skip
# User provides token:
get_next_task { slug, figmaToken: "figd_...", figmaAction: "use" }

# User skips Design2Code:
get_next_task { slug, figmaAction: "skip" }

# CLI equivalent:
spec implement --spec my-feature --next --figma-token figd_...
spec implement --spec my-feature --next --figma-skip

Task type	Who implements
UI, widget, screen, layout	Cursor/Claude (default). Optional Design2Code scaffold if Figma token provided
Wire state / BLoC / navigation / validation / tests	Cursor/Claude via SpecDrive context

Available MCP tools

Tool	Description
`create_spec`	Scaffold dated feature folder + YOUR JOURNEY + brief bundle
`write_spec_document`	Save host-generated markdown; returns documentContent + approval brief
`request_gate_approval`	Build approval brief — show to human and STOP
`update_spec`	Human gate decision (`userConfirmed: true` required)
`generate_gap_analysis`	Gap-analysis bundle (cite real files)
`generate_design_hld`	High-level design bundle
`generate_design_lld`	Low-level design bundle
`generate_tasks`	Checkbox task list bundle (last human gate)
`scan_codebase`	Scan repo for source context
`get_next_task`	Impl when ready_for_implementation; Design2Code optional on UI tasks if user provides Figma token
`get_spec_status`	Phase, gates, ready flag + phase cheat sheet
`figma_status`	Check Design2Code + FIGMA_TOKEN setup
`figma_import`	Import Figma file to Design AST
`figma_generate`	Generate code from Figma/AST
`figma_generate_for_spec`	Generate using spec stack + Figma
`figma_preview`	Preview generated code (no writes)
`review_code`	Review against HLD/LLD + requirements
`search_specs`	List all specs

Marketplace listing

For one-click install via Cursor Marketplace or Claude Connectors Directory, see the marketplace submission guide on GitHub.