noir-mcp-server

MCP server for Noir development — clones and searches Noir documentation, standard library, examples, and community libraries.

Install

Claude Code

claude mcp add noir-mcp -- npx noir-mcp-server@latest

Codex

codex mcp add noir-mcp -- npx noir-mcp-server@latest

Claude Desktop / Cursor / Windsurf

Add to your MCP config file (e.g. ~/.claude/mcp.json, claude_desktop_config.json):

{
  "mcpServers": {
    "noir": {
      "command": "npx",
      "args": ["noir-mcp-server@latest"]
    }
  }
}

OpenCode

Add to your config file (e.g. ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "noir": {
      "type": "local",
      "command": ["npx", "-y", "noir-mcp-server@latest"],
      "enabled": true,
    },
  },
}

From source

git clone https://github.com/critesjosh/noir-mcp-server.git
cd noir-mcp-server
npm install && npm run build

Then point your MCP config to the built file:

{
  "mcpServers": {
    "noir": {
      "command": "node",
      "args": ["/path/to/noir-mcp-server/dist/index.js"]
    }
  }
}

Tools

Tool	Description
noir_sync_repos	Clone/update repos. Default: core only. Add categories: ["libraries"] for packages.
noir_status	Check repo clone status
noir_search_code	Search .nr files across repos
noir_search_docs	Search Noir documentation
noir_search_stdlib	Search standard library
noir_list_examples	List available examples
noir_read_example	Read example source
noir_read_file	Read any file from repos
noir_list_libraries	List libraries with descriptions & clone status

Repository Categories

Core (synced by default):

• noir — Compiler, stdlib, tooling, docs
• noir-examples — Official example circuits

Libraries (sync with categories: ["libraries"]):

• noir-bignum — Big integer arithmetic
• noir_bigcurve — Elliptic curve operations
• noir_json_parser — JSON parsing (RFC 8259)
• noir_string_search — Substring search/proof
• noir_sort — Array sorting
• sparse_array — Sparse array implementation
• zk-kit.noir — Merkle trees, ECDH, and more

Reference (sync with categories: ["reference"]):

• awesome-noir — Curated ecosystem index

When this server helps (and when it doesn't)

Good fit:

• Writing or editing Noir circuits with an AI agent that would otherwise lean on stale, pre-1.0 syntax from memory. The Noir docs and standard library are pinned to a specific release, so the agent works from version-correct language source rather than guessing.
• Looking up how a stdlib function, trait, or type is actually defined or used (e.g. hash, Field, assert, pedersen).
• Finding real, working example circuits to adapt (noir-examples, noir/examples).
• Discovering ecosystem libraries and reading their source.
• Grounding an agent so it stops inventing outdated syntax. Pair it with nargo check to confirm the result compiles.

Poor fit:

• You want guaranteed-correct, compilable output without verifying it yourself. This server does not compile or run anything; always confirm with nargo check.
• You need community libraries to exactly match your pinned compiler. Libraries are cloned at their latest branch, not a release matched to the compiler (see Limitations).
• Conceptual or design questions ("what is the best way to structure a Merkle-membership circuit?"). Search is keyword/regex, not semantic; the model plus the docs site may serve you better.
• Proving-backend workflows beyond reading bb.js source.
• Offline use, or environments without git (and ideally ripgrep) installed.

Limitations

• Read-only, no verification. It surfaces source and docs but does not compile, type-check, or run circuits. It cannot confirm that code is correct; run nargo check against a matching toolchain.
• Core repos are pinned; libraries are not. The noir repo (docs, stdlib, in-repo examples) and bb.js are checked out at a fixed tag; community libraries are cloned at their main/master branch tip, which may be newer or older than the pinned compiler. Noir's compiler_version field only expresses a full-release floor (e.g. >=1.0.0) and cannot distinguish between betas, so it will not flag a beta-level mismatch. Treat library code as a reference and verify it against your toolchain.
• Keyword search, not semantic. Search is ripgrep over files. It excels at finding a known symbol or string and is weak at open-ended "how do I do X" questions.
• Single-line matches. Results are matching lines without surrounding context; reading the full function or doc comment usually needs a follow-up noir_read_file.
• Sync required, and the first sync is slow. Repos are cloned locally over the network before search works. Core is two repos; adding library or reference categories clones more.
• One version at a time. The server serves a single pinned Noir line (see Environment Variables). Switching versions means re-syncing with version, and library compatibility is still not guaranteed.
• Snapshot, not live. Content reflects the pinned tag (docs/stdlib) and your last sync (libraries). Re-sync to pick up updates.
• Host dependencies. Requires git; uses ripgrep when present and falls back to a slower built-in search otherwise.

Environment Variables

Variable	Default	Description
NOIR_DEFAULT_VERSION	v1.0.0-beta.21	Noir version tag for the main repo
NOIR_MCP_REPOS_DIR	~/.noir-mcp	Base directory for cloned repos

Development

npm run dev    # Watch mode
npm run build  # Build
npm start      # Run server
npm test       # Run the Vitest unit suite
node test.mjs  # Optional live integration smoke test (clones repos)