Package Exports

specdown-mcp
specdown-mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (specdown-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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

npm version node downloads

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

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

SpecDown account — free plan available
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

Tool	Description
`list_projects`	List all projects you have access to
`list_documents`	List Markdown documents in a project
`list_project_files`	List preview-only project attachments
`read_document`	Read full Markdown content by ID or project+path
`read_project_file`	Read attachment metadata, text preview, embed ref, and download URL
`search_documents`	Full-text search across all Markdown spec docs
`read_project_context`	Get project overview: tree, README, description
`list_comments`	List inline comments on a document
`add_comment`	Add a comment (anchored to text or threaded reply)
`create_document`	Create a new Markdown document or folder
`update_document`	Replace Markdown content (auto-versioned on change)
`upload_image`	Upload an image asset and return a markdown link
`upload_project_file`	Upload any project attachment and return a `[@/path]` embed reference
`get_sync_status`	Return remote sync snapshots and summary for a project subtree
`plan_sync`	Compare local snapshots with remote docs and produce a sync plan
`apply_sync_plan`	Apply remote upsert/delete operations produced from a sync plan

Environment Variables

Variable	Required	Description
`SPECDOWN_API_KEY`	Yes	Your API key from SpecDown Settings
`SPECDOWN_API_URL`	No	Override API base URL (for self-hosted instances)

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"
}

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

specdown-mcp