# neurarch-mcp [Health: Active]

**Category:** 🧮 Data Science Tools  
**Repository:** https://github.com/neurarch-ai/neurarch-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 878  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/neurarch-mcp

## Description
Reads your PyTorch .py or Neurarch graph so agents can inspect, lint and cost the model.

## Tools
Capabilities this server exposes over MCP:

- **size_training_job** — What a training job needs before it takes a GPU reservation.** Inputs: the model (the server's, `model_path` to a `.py`, a traced `.neurarch.json`, `zoo:<id>` or `hf:<org/name>`, or `hf_id`), `batch_size`, and optionally `gpu` (`"A100-40"`, `"H100"`, `"8xH100"`), `seq_len`, `attention` (`sdpa` defa…
- **diagnose_oom** — Why a job ran out of GPU memory, and the smallest change that fixes it.** Call it after a CUDA out-of-memory error, before changing batch size. Inputs: `error` (the text as printed, either PyTorch wording), and optionally the model (as above, or `hf_id`, read from the local config cache with no net…
- **check_edit** — Whether an edit to a model's config or architecture is one that runs and is wrong, and what it did to memory.** Call it after editing and before training. Inputs: the base (`base_model_path`: a `.py`, a `.neurarch.json`, `zoo:<id>` or `hf:<org/name>`; or `base_config`) and the changed model (the se…
- **plan** — The graph, to `POST /api/v1/plan`. This is the one tool that sends the model.
- **history** — The fingerprint and your key. **Never the graph.
- **describe_architecture** — One-call orientation: topo-ordered pipeline, depth, IO shapes, total params and MACs, top-5 param **and** compute hotspots, validation rollup. Start here.
- **get_model_summary** — Layer count, total params, dominant types, input/output shape.
- **get_layer** — One layer by name: params, shapes, notes, upstream/downstream.
- **find_layers** — Search by type, name regex, scope prefix or augmentation; rank by parameter count.
- **compare_layers** — Structural diff of two layers.
- **layer_impact** — Blast radius** of changing a layer or matched set: shape-sensitive and weight-carrying downstream layers. Call it before recommending an edit.
- **diff_models** — Structural diff against another `.neurarch.json`.
- **mermaid_diagram** — The model as Mermaid `flowchart TD`.
- **list_architectures** — Search the **81 reference architectures bundled with this server** (DeepSeek-V3, Qwen2.5, Llama, Mixtral, Gemma, Whisper, CLIP, BERT, ViT, ResNet and more), each with real dimensions from the model's config and a parameter count checked against the published one. Offline.
- **load_architecture** — Open one and describe it. Then `model_path: "zoo:<id>"` on any tool.
- **load_hf_model** — A Hugging Face repo as a graph. Listed only under `--hf`, because it is the one tool that opens a socket.
- **find_models** — Walk a directory for nn.Module definitions and saved graphs, try the parser on each, and say which need `neurarch-trace` instead.
- **trace_model** — Run `neurarch-trace` in your Python with the input dims and get a graph with real shapes back as a `model_path`. **The primary way in for a real repository**, not a fallback: the static parser returns a recognisable graph for 41% of real model files and no finding it raised on one has yet been a re…
- **export_pytorch** — The graph as a runnable `nn.Module`, the app's own generator. `save_to` needs `--write` and never targets the file the server was started from.

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

```json
"mcpServers": {
  "neurarch-mcp": {
    "command": "npx",
    "args": ["-y","neurarch-mcp"]
  }
}
```

## Documentation

## What neurarch-mcp MCP server does

The neurarch-mcp MCP server lets an agent inspect a PyTorch model as a structured graph instead of inferring architecture details from source text. It accepts a self-contained `.py` file, a saved `.neurarch.json` graph, a bundled reference architecture, or—when started with `--hf`—a Hugging Face repository. The server can also discover model definitions and saved graphs in a directory with `find_models`.

The main orientation tool is `describe_architecture`. It returns a topology-ordered pipeline, graph depth, input and output shapes, total parameters and MACs, the largest parameter and compute hotspots, and a validation rollup. More targeted tools expose model summaries, individual layers, searches, structural comparisons, downstream impact, model diffs, Mermaid diagrams, and runnable PyTorch export.

## How it works

For source files, the server statically parses layer definitions and wiring. This path can identify layers, types, hyperparameters, and connections, but it cannot reliably recover runtime shapes or FLOPs when those values are created dynamically. A saved graph carries richer information, including shapes, groups, and design notes.

`trace_model` runs `neurarch-trace` in the user’s Python environment with supplied input dimensions and returns a graph path containing runtime shapes. The README presents tracing as the preferred route for real repositories, including models spread across files, dynamically constructed models, and code using `from_pretrained` or timm. `load_architecture` opens one of the 81 bundled reference architectures, which include families such as Llama, Qwen, DeepSeek, Mixtral, Gemma, Whisper, CLIP, BERT, ViT, and ResNet. These references are offline and include configuration-derived dimensions and checked parameter counts.

The `plan` tool sends the graph to `POST /api/v1/plan`; `history` sends a fingerprint and key without sending the graph. These are the only listed operations described as opening a network connection.

## Setup and configuration

Node 20 or newer is required. For a local model file, run the server with `npx`, for example:

```bash
npx -y neurarch-mcp /absolute/path/to/model.py
```

The README provides client-specific setup for Claude Code, Cursor, Claude Desktop, VS Code, Windsurf, and Codex. A saved graph can be watched with `--watch` so app-side saves become visible without restarting the server. Hugging Face loading requires the `--hf` option, and `load_hf_model` is the listed tool that opens a socket for that purpose.

Tracing requires the separate `neurarch-trace` Python package. It can trace a callable with input dimensions or record the first forward pass when enabled in a training script.

## Limitations and notes

Static parsing is a fallback rather than a substitute for tracing on complex repositories. The referenced study found a recognizable graph for 41% of 116 real model files; source-derived shapes and compute values may be unknown. The README also reports that static-parser findings should be treated cautiously and recommends tracing before acting on them.

`export_pytorch` writes only when started with `--write`, and it must not target the file used to start the server. `plan` and `history` have different privacy and connectivity behavior from the offline inspection tools: `plan` sends the model graph, while `history` does not send the graph.

The neurarch-mcp MCP server can inspect a Hugging Face repository only through the explicitly enabled `--hf` mode. For an ordinary local analysis, no API key or account is described as required.

_Full upstream README: https://allmcps.com/mcp/neurarch-mcp/readme_