@locus-dev/mcp-server

Give your AI coding agent the spec it should be reading before writing code.

MCP server for Locus — exposes your stories.yaml as structured resources and tools for Claude Code, Cursor, Windsurf, Zed, OpenAI Codex, Continue.dev, GitHub Copilot, and any MCP-compatible client.

stories.yaml is the single source of truth for your product requirements. It lives in your repo. No account required.

Quick start — zero config

Add one entry to your Claude Code config (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@locus-dev/mcp-server"]
    }
  }
}

That's it. No API keys, no credentials, no account.

The server reads stories.yaml from your project directory automatically.

Compatible with Claude Code, Codex, Cursor, Continue.dev, GitHub Copilot, and any MCP-compatible coding agent.

stories.yaml belongs to you. It lives in your repo. Switch AI tools anytime — your spec stays intact.

How it works

1. Add a stories.yaml file to your project root (see schema docs)
2. Add the MCP server to your AI client config (above)
3. Your AI coding assistant now sees what needs to be built, what the acceptance criteria are, and what's already done

The server finds stories.yaml automatically:

1. LOCUS_STORIES_PATH env var if set
2. stories.yaml in the current directory
3. Walks up to find stories.yaml at the repo root (stops at .git)
4. Also accepts stories.yml and stories.json

Client setup guides

• Claude Code
• Cursor
• OpenAI Codex CLI
• Windsurf
• Zed
• Continue.dev
• GitHub Copilot (VS Code)

Cloud mode (optional)

If you use the Locus platform for team sync, set these environment variables to enable cloud mode:

Cloud mode config example:

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@locus-dev/mcp-server"],
      "env": {
        "PROTOTYPER_API_KEY": "your-jwt",
        "PROTOTYPER_SUPABASE_URL": "https://your-project.supabase.co",
        "PROTOTYPER_PROJECT_ID": "optional-project-uuid"
      }
    }
  }
}

If PROTOTYPER_API_KEY and PROTOTYPER_SUPABASE_URL are both set, cloud mode activates automatically. Otherwise, file mode is used.

Environment variables

Tools

list_stories

List user stories with optional filters.

list_stories(status="not-implemented", section="Leave Management")

Parameters:

• project_id (optional) — file mode: always local; cloud mode: defaults to PROTOTYPER_PROJECT_ID
• status — not-implemented | partial | implemented | stale | deprecated | all (default: all)
• section — case-insensitive partial match on story section

get_story

Get full detail for a single story.

get_story(story_id="US-04")

Parameters:

• story_id (required) — e.g. US-01, AUTH-03
• project_id (optional)

Returns: Full story YAML including description and acc

... View full README on GitHub