# Spiderbrain [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/aabhisrv/Spiderbrain.ai-Coremind  
**GitHub Stars:** 3  
**npm Downloads (last month):** 152  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/spiderbrain

## Description
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "spiderbrain": {
    "command": "npx",
    "args": ["-y","spiderbrain"],
    "env": {
      "SPIDERBRAIN_ROOT": "",
      "SPIDERBRAIN_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `SPIDERBRAIN_ROOT`, `SPIDERBRAIN_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Spiderbrain MCP server does

Spiderbrain MCP server gives coding agents access to a repository understanding layer stored in `.spiderbrain/`. The layer records source-free information about file paths, structure, dependencies, and derived blast-radius relationships. It does not contain the repository’s source code or scoring weights.

The reader can answer which files a change may reach, which files are load-bearing, how one file connects to another, and what a file touches. Results are deterministic when they come from the same committed understanding data: the same repository state and question produce the same answer. Each folder includes a fingerprint that the reader checks so edited or corrupted data is detected.

## How it works

Start the MCP process with the Spiderbrain CLI and point it at the repository that contains `.spiderbrain/`. The server exposes six agent tools: `sb_blast`, `sb_impact`, `sb_path`, `sb_keystones`, `sb_map`, and `sb_ask`. Commands and tools return structured information suitable for coding agents; the CLI also supports `--json` for machine-readable output.

The local reader works offline for structure, dependency, blast-radius, and keystone queries. If the repository has no local understanding folder, it can check the public SpiderBrain registry for an unofficial, fingerprint-verified brain matched using the repository’s `origin` remote. A local committed folder takes precedence.

Cloud features require an API key. They add recorded reasoning for a file, current scores, and semantic search; these are separate from the deterministic offline queries.

## Setup and configuration

Install or run the package through `npx`:

```bash
npx spiderbrain mcp --root /path/to/repository
```

The `--root` option is important because an MCP client’s working directory may not be the repository being queried. The same location can be supplied as `--root=<path>` or with `SPIDERBRAIN_ROOT`. Without an explicit root, the process examines its working directory and reports that no understanding layer was found if `.spiderbrain/` is elsewhere.

No account, local SpiderBrain installation, or additional MCP configuration is required for the reader. To create a local understanding folder from the cloud service, set `SPIDERBRAIN_API_KEY` and run `npx spiderbrain create`; that workflow also writes an `AGENTS.md` block. Commit the generated `.spiderbrain/` folder if agents should use it later.

## Tools and capabilities

- `sb_blast`: inspect the files reached by changing a specified file.
- `sb_impact`: inspect the likely reach of the current diff.
- `sb_path`: trace how one file reaches another.
- `sb_keystones`: identify load-bearing files in the repository.
- `sb_map`: view what a file is and what it touches.
- `sb_ask`: ask questions against the available understanding layer.

The command-line interface provides corresponding operations such as `blast`, `impact`, `path`, `keystones`, `map`, and `verify`. Exit codes distinguish successful queries, failed checks, usage errors, and a missing understanding layer. CI workflows can use options such as `--fail-over` to reject a change whose blast radius exceeds a threshold.

## Limitations and notes

Spiderbrain MCP server reads the published understanding data; it does not reconstruct the repository’s source code during a query. Answers are limited by the files and relationships captured in the layer. A committed folder is normally behind the current commit because committing the folder creates another commit, so `verify --allow-stale` permits that specific freshness condition while retaining the integrity check. Use `verify` without that flag when the brain was generated for the exact commit under test.

The scoring engine that produces the brain is proprietary. The open packages provide the folder specification, reader, MCP server, and producer client. The project and its packages are MIT licensed.

_Full upstream README: https://allmcps.com/mcp/spiderbrain/readme_