SpecDown MCP Server — AI-Native Markdown MCP for AI Assistants

AI-native Markdown MCP server for SpecDown — give Claude, Cursor, Copilot, and other AI coding assistants direct read/write access to your Markdown spec documents.

Stop copy-pasting specs into AI chat. Connect once, AI reads your Markdown docs forever — AI-native spec-driven development.

Jump to your IDE: Cursor • Claude Desktop • Claude Code • Windsurf • OpenCode • VS Code • Codex CLI

What is AI-Native Markdown MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external tools and data sources. specdown-mcp is an AI-native Markdown MCP server that exposes your SpecDown spec documents as MCP resources — so Claude, Cursor, and other AI tools can read, search, and edit your specs directly.

AI-native Spec as Code + AI = spec-driven development:

Engineer writes Markdown spec → AI reads spec via MCP → AI implements feature from spec

Related MCP server: MCP Docs Provider

Features

• Read & search Markdown docs — list projects, browse document tree, full-text search

• Edit docs — update Markdown content, create new documents (auto-versioned)

• Upload images — attach image assets and get markdown links back for documents

• Inline comments — add and list comments anchored to specific text

• Sync planning for agents — inspect remote snapshots, plan local-vs-remote sync, and apply remote sync operations

• AI-native spec-driven development — give AI full Markdown context with zero copy-paste

• 13 MCP tools — complete read/write and sync-planning API for your spec documents

• MCP resources — specdown://projects, specdown://project/{id}

Prerequisites

1. SpecDown account — free plan available

2. API key — generate at Settings → API Keys

Quick Start

No install needed — npx runs it on demand:

# Verify it works
SPECDOWN_API_KEY=your_key npx specdown-mcp

IDE Configuration

Replace YOUR_API_KEY with your key from SpecDown Settings.

Cursor

Config path: .cursor/mcp.json (project) or ~/.cursor/mcp.json (global)

{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": {
        "SPECDOWN_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop

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

{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": {
        "SPECDOWN_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": {
        "SPECDOWN_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Windsurf

Config path: ~/.windsurf/mcp.json or .windsurf/mcp.json (project)

{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": {
        "SPECDOWN_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

OpenCode

Config path: opencode.json (project root) or ~/.config/opencode/opencode.json

{
  "mcpServers": {
    "specdown": {
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": {
        "SPECDOWN_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

VS Code

Config path: .vscode/mcp.json

{
  "servers": {
    "specdown": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "specdown-mcp"],
      "env": {
        "SPECDOWN_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Codex CLI

Config path: ~/.codex/config.toml

[mcp_servers.specdown]
command = "npx"
args = ["-y", "specdown-mcp"]

[mcp_servers.specdown.env]
SPECDOWN_API_KEY = "YOUR_API_KEY"

Available MCP Tools

Environment Variables

Troubleshooting

Error: SPECDOWN_API_KEY must be set → Add SPECDOWN_API_KEY to the env block in your IDE's MCP config.

Unauthorized or 401 → Key may be invalid or expired. Regenerate at Settings → API Keys.

Server not appearing in IDE → Restart the IDE after editing MCP config. Cursor: Cmd+Shift+P → "MCP: Reload Servers".

npx: command not found → Install Node.js ≥ 18 from nodejs.org.

Self-hosted SpecDown

Point the MCP server at your own instance:

"env": {
  "SPECDOWN_API_KEY": "YOUR_API_KEY",
  "SPECDOWN_API_URL": "https://your-specdown.example.com"
}

Related

• SpecDown — Markdown editor online, Spec as Code platform

• specdown-cli — Markdown CLI for terminal, CI/CD, and automation

• Get API Key

• Report issue

License

MIT