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

npm version node downloads

MCP server for SpecDown — let Claude, Cursor, and other AI coding assistants read, search, and edit your Markdown spec documents. Spec-as-Code, AI-ready.

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

Features

Read & search — list projects, browse documents, full-text search across all specs
Edit & comment — update docs, add inline comments, create new documents
Spec-driven AI — give AI full context from your Markdown specs with zero copy-paste
9 tools — list_projects, list_documents, read_document, search_documents, read_project_context, list_comments, add_comment, create_document, update_document
Resources — specdown://projects, specdown://project/{id}

Prerequisites

SpecDown account — sign up free
API key — get yours from Settings → API Keys

Quick Start

No install needed. Add to your IDE's MCP config and it runs automatically via npx.

# Test it works:
npx specdown-mcp --help

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 Linux: ~/.config/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"

Environment Variables

Variable	Required	Default	Description
`SPECDOWN_API_KEY`	Yes	—	Your API key from SpecDown Settings
`SPECDOWN_API_URL`	No	`https://specdown.app`	API base URL — for self-hosted instances
`SPECDOWN_SUPABASE_URL`	No	built-in	Override Supabase URL for self-hosted
`SPECDOWN_SUPABASE_ANON_KEY`	No	built-in	Override Supabase anon key for self-hosted

Available Tools

Tool	Description
`list_projects`	List all projects you have access to
`list_documents`	List documents in a project
`read_document`	Read full markdown content by ID or project+path
`search_documents`	Full-text search across all documents
`read_project_context`	Get project overview: tree, README, description
`list_comments`	List comments on a document
`add_comment`	Add a comment (anchored to text or threaded reply)
`create_document`	Create a new document or folder
`update_document`	Replace document content (auto-versions on change)

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 → Your key may be invalid or expired. Generate a new one 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 server at your own instance:

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

License

MIT

specdown-mcp