narsil-mcp

The blazing-fast, privacy-first MCP server for deep code intelligence

A Rust-powered MCP (Model Context Protocol) server providing AI assistants with deep code understanding through 90 specialized tools.

Why narsil-mcp?

Key Features

• Code Intelligence - Symbol extraction, semantic search, call graph analysis
• Neural Semantic Search - Find similar code using embeddings (Voyage AI, OpenAI)
• Security Analysis - Taint analysis, vulnerability scanning, OWASP/CWE coverage
• Supply Chain Security - SBOM generation, dependency auditing, license compliance
• Advanced Analysis - Control flow graphs, data flow analysis, dead code detection

Why Choose narsil-mcp?

• Written in Rust - Blazingly fast, memory-safe, single binary (~30MB)
• Tree-sitter powered - Accurate, incremental parsing for 32 languages
• Zero config - Point at repos and go
• MCP compliant - Works with Claude, Cursor, VS Code Copilot, Zed, and any MCP client
• Privacy-first - Fully local, no data leaves your machine
• Parallel indexing - Uses all cores via Rayon
• Smart excerpts - Expands to complete syntactic scopes
• Security-first - Built-in vulnerability detection and taint analysis
• Neural embeddings - Optional semantic search with Voyage AI or OpenAI
• WASM support - Run in browser with WebAssembly build
• Real-time streaming - Results as indexing progresses for large repos

Supported Languages

Installation

Via Package Managers (Recommended)

macOS / Linux (Homebrew):

brew tap postrv/narsil
brew install narsil-mcp

Windows (Scoop):

scoop bucket add narsil https://github.com/postrv/scoop-narsil
scoop install narsil-mcp

Rust/Cargo (all platforms):

cargo install narsil-mcp

Node.js/npm (all platforms):

npm install -g narsil-mcp
# or
yarn global add narsil-mcp
# or
pnpm add -g narsil-mcp

Nix:

# Run directly without installing
nix run github:postrv/narsil-mcp -- --repos ./my-project

# Install to profile
nix profile install github:postrv/narsil-mcp

# With web visualization frontend
nix profile install github:postrv/narsil-mcp#with-frontend

# Development shell
nix develop github:postrv/narsil-mcp

One-Click Install Script

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.ps1 | iex

Windows (Git Bash / MSYS2):

curl -fsSL https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.sh | bash

Note for Windows users: The PowerShell installer provides better error messages and native Windows integration. It will automatically configure your PATH and check for required build tools if building from source.

From Source

Prerequisites:

• Rust 1.70 or later
• On Windows: Visual Studio Build Tools with "Desktop development with C++"

# Clone and build
git clone git@github.com:postrv/narsil-mcp.git
cd narsil-mcp
cargo build --release

# Binary will be at:
# - macOS/Linux: target/release/narsil-mcp
# - Windows: target/release/narsil-mcp.exe

Feature Builds

narsil-mcp supports different feature sets for different use cases:

# Default build - native MCP server (~30MB)
cargo build --release

# With RDF knowledge graph and CCG tools (~35MB) - SPARQL queries, Code Context Graph
cargo build --release --features graph

# With neural vector search (~32MB) - adds TF-IDF similarity
cargo build --release --features neural

# With ONNX model support (~50MB) - adds local neural embeddings
cargo build --release --features neural-onnx

# With embedded visualization frontend (~31MB)
cargo build --release --features frontend

# Full-featured build with graph + frontend (~40MB)
cargo build --release --features graph,frontend

# For browser/WASM usage
cargo build --release --target wasm32-unknown-unknown --features wasm

Important: The --graph CLI flag requires the binary to be built with --features graph. If you pass --graph to a binary built without this feature, you'll see a warning and SPARQL/CCG tools won't be available. See Troubleshooting below.

For detailed installation instructions, troubleshooting, and platform-specific guides, see docs/INSTALL.md.

Usage

Basic Usage

macOS / Linux:

# Index a single repository
narsil-mcp --repos /path/to/your/project

# Index multiple repositories
narsil-mcp --repos ~/projects/project1 --repos ~/projects/project2

# Enable verbose logging
narsil-mcp --repos /path/to/project --verbose

# Force re-index on startup
narsil-mcp --repos /path/to/project --reindex

Windows (PowerShell / CMD):

# Index a single repository
narsil-mcp --repos C:\Users\YourName\Projects\my-project

# Index multiple repositories
narsil-mcp --repos C:\Projects\project1 --repos C:\Projects\project2

# Enable verbose logging
narsil-mcp --repos C:\Projects\my-project --verbose

# Force re-index on startup
narsil-mcp --repos C:\Projects\my-project --reindex

Full Feature Set

narsil-mcp \
  --repos ~/projects/my-app \
  --git \           # Enable git blame, history, contributors
  --call-graph \    # Enable function call analysis
  --persist \       # Save index to disk for fast startup
  --watch \         # Auto-reindex on file changes
  --lsp \           # Enable LSP for hover, go-to-definition
  --streaming \     # Stream large result sets
  --remote \        # Enable GitHub remote repo support
  --neural \        # Enable neural semantic embeddings
  --neural-backend api \  # Backend: "api" (Voyage/OpenAI) or "onnx"
  --neural-model voyage-code-2 \  # Model to use
  --neural-dimension 3072 \  # Override embedding dimensions (auto-detected per model)
  --graph           # Enable SPARQL/RDF knowledge graph and CCG tools (requires --features graph build)

Note about --graph: This flag enables SPARQL queries and Code Context Graph (CCG) tools, but only if the binary was built with --features graph. The default binary does not include this feature. If you need SPARQL/CCG capabilities, build from source with:

cargo build --release --features graph

If you pass --graph to a binary without the feature, you'll see a warning at startup and the server will cont