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?

| Feature | narsil-mcp | XRAY | Serena | GitHub MCP | |---------|------------|------|--------|------------| | Languages | 32 | 4 | 30+ (LSP) | N/A | | Neural Search | Yes | No | No | No | | Taint Analysis | Yes | No | No | No | | SBOM/Licenses | Yes | No | No | Partial | | Offline/Local | Yes | Yes | Yes | No | | WASM/Browser | Yes | No | No | No | | Call Graphs | Yes | Partial | No | No | | Type Inference | Yes | No | No | No |

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

| Language | Extensions | Symbols Extracted | |----------|------------|-------------------| | Rust | .rs | functions, structs, enums, traits, impls, mods | | Python | .py, .pyi | functions, classes | | JavaScript | .js, .jsx, .mjs | functions, classes, methods, variables | | TypeScript | .ts, .tsx | functions, classes, interfaces, types, enums | | Go | .go | functions, methods, types | | C | .c, .h | functions, structs, enums, typedefs | | C++ | .cpp, .cc, .hpp | functions, classes, structs, namespaces | | Java | .java | methods, classes, interfaces, enums | | C# | .cs | methods, classes, interfaces, structs, enums, delegates, namespaces | | Bash | .sh, .bash, .zsh | functions, variables | | Ruby | .rb, .rake, .gemspec | methods, classes, modules | | Kotlin | .kt, .kts | functions, classes, objects, interfaces | | PHP | .php, .phtml | functions, methods, classes, interfaces, traits | | Swift | .swift | classes, structs, enums, protocols, functions | | Verilog/SystemVerilog | .v, .vh, .sv, .svh | modules, tasks, functions, interfaces, classes | | Scala | .scala, .sc | classes, objects, traits, functions, vals | | Lua | .lua | functions, methods | | Haskell | .hs, .lhs | functions, data types, type classes | | Elixir | .ex, .exs | modules, functions | | Clojure | .clj, .cljs, .cljc, .edn | lists (basic AST) | | Dart | .dart | functions, classes, methods | | Julia | .jl | functions, modules, structs | | R | .R, .r, .Rmd | functions | | Perl | .pl, .pm, .t | functions, packages | | Zig | .zig | functions, variables | | Erlang | .erl, .hrl | functions, modules, records | | Elm | .elm | functions, types | | Fortran | .f90, .f95, .f03, .f08 | programs, subroutines, functions, modules | | PowerShell | .ps1, .psm1, .psd1 | functions, classes, enums | | Nix | .nix | bindings | | Groovy | .groovy, .gradle | methods, classes, interfaces, enums, functions |

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

Arch Linux (AUR):

yay -S narsil-mcp-bin  # Binary release (faster)
# or
yay -S narsil-mcp      # Build from source

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

| Feature | Description | Size | |---------|-------------|------| | native (default) | Full MCP server with all tools | ~30MB | | graph | + RDF knowledge graph, SPARQL, CCG tools | ~35MB | | frontend | + Embedded visualization web UI | ~31MB | | neural | + TF-IDF vector search, API embeddings | ~32MB | | neural-onnx | + Local ONNX model inference | ~50MB | | wasm | Browser build (no file system, git) | ~3MB |

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