Model Context Protocol (MCP) Server: ai.spiderbrain/spiderbrain

The ai.spiderbrain/spiderbrain MCP server provides a deterministic context layer for a codebase. It focuses on “change impact” and “blast radius” and aims to produce answers with “receipts,” using a repo understanding approach defined by Spiderbrain.

🛠️ Key Features

Deterministic context layer for codebase understanding
Emphasis on change impact and blast radius
Answers with receipts
Uses the “committed understanding layer” concept for repositories

🚀 Use Cases

Supplying AI agents with a structured understanding of what a repository is
Supporting analysis workflows where the reach of changes matters

⚡ Developer Benefits

Helps an AI agent avoid source-free, repo-only “what” without “what matters”
Adds context intended to cover why design choices and reach are relevant

⚠️ Limitations

The excerpt indicates a source-free .spiderbrain/ folder is written (implying it is not a full source replacement)

spiderbrain

A committed understanding layer for your repo, and the one command to work with it. A repo tells an AI agent what the code is; it never tells it what matters, what a change reaches, or why anything was built the way it was. spiderbrain fixes that.

Read a repo's understanding (no account needed)

When a repo has a .spiderbrain/ folder, any agent or developer can use it offline:

code

npx spiderbrain mcp --root .        # an MCP server for Claude Code / Cursor
npx spiderbrain blast src/db.ts     # what a change here reaches
npx spiderbrain impact              # what your current git diff reaches
npx spiderbrain keystones           # the load-bearing files
npx spiderbrain path a.ts b.ts      # how one file reaches another
npx spiderbrain verify --allow-stale   # folder untampered? (CI gate)

An MCP client's working directory is usually not your repository, so pass the repo explicitly with --root <path>, --root=<path>, or the SPIDERBRAIN_ROOT environment variable. Without it the server serves the working directory and reports that no understanding layer was found, which is a wrong answer rather than an error.

Every command takes --json (exit codes: 0 ok, 1 failed, 2 usage, 3 no understanding). No committed folder? The reader falls back to the public registry when the repo's origin has an unofficial brain there.

The pieces

spiderbrain is a thin dispatcher over two independently installable packages:

@spiderbrain/read — consume: reader, CLI, MCP server. Zero dependencies.

@spiderbrain/create — produce: fetch your scored brain and write the understanding set.

A CI job that only publishes understanding can depend on @spiderbrain/create alone; an MCP config that only reads can point at @spiderbrain/read. spiderbrain is what you type when you just want the thing.

Install

Configuration

Environment variables

SPIDERBRAIN_ROOTrequired

Absolute path to the repository to serve, which must already contain a committed .spiderbrain/ folder. Set this: an MCP client's working directory is usually not your repository, and without it the server serves the working directory and reports that no understanding layer was found. Equivalent to passing --root.

SPIDERBRAIN_API_KEYsecret

Optional. Enables the cloud why-layer used by the sb_ask tool. The structural tools work offline without it.

SPIDERBRAIN_REGISTRY

Optional. Base URL of the public brain registry this server consults on the first tool call when the repository has no committed .spiderbrain/ folder. Defaults to https://spiderbrain.ai/registry.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "spiderbrain": {
      "command": "npx",
      "args": [
        "-y",
        "spiderbrain@0.2.3",
        "mcp"
      ],
      "env": {
        "SPIDERBRAIN_ROOT": "<YOUR_SPIDERBRAIN_ROOT>",
        "SPIDERBRAIN_API_KEY": "<YOUR_SPIDERBRAIN_API_KEY>",
        "SPIDERBRAIN_REGISTRY": "<YOUR_SPIDERBRAIN_REGISTRY>"
      }
    }
  }
}

Spiderbrain