narsil-mcp

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, .f, .for, .fpp	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

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:

• Current stable Rust (this release was verified with Rust 1.98 and 1.99)
• 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

# Experimental browser/WASM source build (not release-qualified)
cargo build --release --target wasm32-unknown-unknown --no-default-features --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	Experimental browser source build (no file system, git)	Not release-qualified

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 continue without SPARQL/CCG tools.

Note: Neural embeddings require an API key (or custom endpoint). The easiest way to set this up is with the interactive wizard:

# Run the neural API key setup wizard
narsil-mcp config init --neural

The wizard will:

• Detect your editor (Claude Desktop, Claude Code, Zed, VS Code, JetBrains)
• Prompt for your API provider (Voyage AI, OpenAI, or custom)
• Validate your API key
• Automatically add it to your editor's MCP config

Alternatively, you can manually set one of these environment variables:

• EMBEDDING_API_KEY - Generic API key for any provider
• VOYAGE_API_KEY - Voyage AI specific API key
• OPENAI_API_KEY - OpenAI specific API key
• EMBEDDING_SERVER_ENDPOINT - Custom embedding API endpoint URL (optional, allows using self-hosted models)

Configuration

v1.1.0+ introduces optional configuration for fine-grained control over tools and performance. All existing usage continues to work - configuration is completely optional!

Quick Start

# Generate default config interactively
narsil-mcp config init

# List available tools
narsil-mcp tools list

# Apply a preset via CLI
narsil-mcp --repos ~/project --preset minimal

Automatic Editor Detection

narsil-mcp detects your editor and applies an optimal preset automatically:

Editor	Preset	Tools	Context Tokens	Why
Zed	Minimal	26	~4,686	Fast startup, minimal context
VS Code	Balanced	51	~8,948	Good feature balance
Claude Desktop	Full	90	~12,001	Maximum capabilities

Token Savings:

• Minimal preset: 61% fewer tokens vs Full
• Balanced preset: 25% fewer tokens vs Full

Presets

Choose a preset based on your use case: