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 76 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 16 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

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

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 neural vector search (~18MB) - 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

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

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

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:

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:

# Minimal - Fast, lightweight (Zed, Cursor)
narsil-mcp --repos ~/project --preset minimal

# Balanced - Good defaults (VS Code, IntelliJ)
narsil-mcp --repos ~/project --preset balanced --git --call-graph

# Full - All features (Claude Desktop, comprehensive analysis)
narsil-mcp --repos ~/project --preset full --git --call-graph

# Security-focused - Security and supply chain tools
narsil-mcp --repos ~/project --preset security-focused

Configuration Files

User config (~/.config/narsil-mcp/config.yaml):

version: "1.0"
preset: "balanced"

tools:
  # Disable slow tools
  overrides:
    neural_search:
      enabled: false
      reason: "Too slow for interactive use"

performance:
  max_tool_count: 50  # Limit total tools

Project config (.narsil.yaml in repo root):

version: "1.0"
preset: "security-focused"  # Override user preset

tools:
  categories:
    Security:
      enabled: true
    SupplyChain:
      enabled: true

Priority: CLI flags > Environment vars > Project config > User config > Defaults

Environment Variables

# Apply preset
export NARSIL_PRESET=minimal

# Enable specific categories
export NARSIL_ENABLED_CATEGORIES=Repository,Symbols,Search

# Disable specific tools
export NARSIL_DISABLED_TOOLS=neural_search,generate_sbom

CLI Commands

# View effective config
narsil-mcp config show

# Validate config file
narsil-mcp config validate ~/.config/narsil-mcp/config.yaml

# List tools by category
narsil-mcp tools list --category Search

# Search for tools
narsil-mcp tools search "git"

# Export config
narsil-mcp config export > my-config.yaml

Learn More:

• Configuration Guide - Full configuration reference
• Installation Guide - Platform-specific installation

Visualization Frontend

Explore call graphs, imports, and code structure interactively in your browser.

# Build with embedded frontend
cargo build --release --features frontend

# Run with HTTP server
narsil-mcp --repos ~/project --http --call-graph
# Open http://localhost:3000

Features: interactive graphs, complexity overlays, security highlighting, multiple layouts.

Full documentation: See docs/frontend.md for setup, API endpoints, and development mode.

Neural Semantic Search

Find similar code using neural embeddings - even when variable names and structure differ.

# Quick setup with wizard
narsil-mcp config init --neural

# Or manually with Voyage AI
export VOYAGE_API_KEY="your-key"
narsil-mcp --repos ~/project --neural --neural-model voyage-code-2

Supports Voyage AI, OpenAI, custom endpoints, and local ONNX models.

Full documentation: See docs/neural-search.md for setup, backends, and use cases.

Type Inference

Built-in type inference for Python, JavaScript, and TypeScript - no mypy or tsc required.

def process(data):
    result = data.split(",")  # result: list[str]
    count = len(result)       # count: int
    return count * 2          # returns: int

MCP Configuration

Add narsil-mcp to your AI assistant by creating a configuration file. Here are the recommended setups:

Claude Code (.mcp.json in project root - Recommended):

Create .mcp.json in your project directory for per-project configuration:

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git", "--call-graph"]
    }
  }
}

Then start Claude Code in your project:

cd /path/to/project
claude

Using . for --repos automatically indexes the current directory. Claude now has access to 76 code intelligence tools.

Tip: Add --persist --index-path .claude/cache for faster startup on subsequent runs.

For global configuration, edit ~/.claude/settings.json instead. See Claude Code Integration for advanced setups.

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git", "--call-graph"]
    }
  }
}

VS Code + GitHub Copilot (.vscode/mcp.json):

{
  "servers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git", "--call-graph"]
    }
  }
}

Note for Copilot Enterprise: MCP support requires VS Code 1.102+ and must be enabled by your organization administrator.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", "/path/to/your/projects", "--git"]
    }
  }
}

Zed (settings.json → Context Servers):

{
  "context_servers": {
    "narsil-mcp": {
      "command": "narsil-mcp",
      "args": ["--repos", ".", "--git"]
    }
  }
}

Note for Zed: narsil-mcp starts immediately and indexes in the background, preventing initialization timeouts.

Claude Code Plugin

For Claude Code users, we provide a plugin with slash commands and a skill for effective tool usage.

Install via Marketplace (Recommended):

# Add the narsil-mcp marketplace
/plugin marketplace add postrv/narsil-mcp

# Install the plugin
/plugin install narsil@narsil-mcp

Or install directly from GitHub:

/plugin install github:postrv/narsil-mcp/narsil-plugin

What's included:

See narsil-plugin/README.md for full documentation.

Playbooks & Tutorials

See docs/playbooks for practical usage guides:

Each playbook shows the exact tool chains Claude uses to answer your questions.

WebAssembly (Browser) Usage

narsil-mcp can run entirely in the browser via WebAssembly - perfect for browser-based IDEs, code review tools, or educational platforms.

npm install @narsil-mcp/wasm

import { CodeIntelClient } from '@narsil-mcp/wasm';

const client = new CodeIntelClient();
await client.init();
client.indexFile('src/main.rs', rustSourceCode);
const symbols = client.findSymbols('Handler');

Full documentation: See docs/wasm.md for build instructions, React examples, and API reference.

Available Tools (76)

Repository & File Management

Symbol Search & Navigation

Code Search

AST-Aware Chunking

Neural Semantic Search (requires --neural)

Call Graph Analysis (requires --call-graph)

Control Flow Analysis

Data Flow Analysis

Type Inference (Python/JavaScript/TypeScript)

Import/Dependency Graph

Security Analysis - Taint Tracking

Security Analysis - Rules Engine

Supply Chain Security

Git Integration (requires --git)

LSP Integration (requires --lsp)

Remote Repository Support (requires --remote)

Metrics

Security Rules

narsil-mcp includes built-in security rules in rules/:

• owasp-top10.yaml - OWASP Top 10 2021 vulnerability patterns
• cwe-top25.yaml - CWE Top 25 Most Dangerous Weaknesses
• crypto.yaml - Cryptographic issues (weak algorithms, hardcoded keys)
• secrets.yaml - Secret detection (API keys, passwords, tokens)

Custom rules can be loaded with scan_security --ruleset /path/to/rules.yaml.

Architecture

+-----------------------------------------------------------------+
|                         MCP Server                               |
|  +-----------------------------------------------------------+  |
|  |                   JSON-RPC over stdio                      |  |
|  +-----------------------------------------------------------+  |
|                              |                                   |
|  +---------------------------v-------------------------------+  |
|  |                   Code Intel Engine                        |  |
|  |  +------------+ +------------+ +------------------------+  |  |
|  |  |  Symbol    | |   File     | |    Search Engine       |  |  |
|  |  |  Index     | |   Cache    | |  (Tantivy + TF-IDF)    |  |  |
|  |  | (DashMap)  | | (DashMap)  | +------------------------+  |  |
|  |  +------------+ +------------+                              |  |
|  |  +------------+ +------------+ +------------------------+  |  |
|  |  | Call Graph | |  Taint     | |   Security Rules       |  |  |
|  |  |  Analysis  | |  Tracker   | |   Engine               |  |  |
|  |  +------------+ +------------+ +------------------------+  |  |
|  +-----------------------------------------------------------+  |
|                              |                                   |
|  +---------------------------v-------------------------------+  |
|  |                Tree-sitter Parser                          |  |
|  |  +------+ +------+ +------+ +------+ +------+             |  |
|  |  | Rust | |Python| |  JS  | |  TS  | | Go   | ...         |  |
|  |  +------+ +------+ +------+ +------+ +------+             |  |
|  +-----------------------------------------------------------+  |
|                              |                                   |
|  +---------------------------v-------------------------------+  |
|  |                Repository Walker                           |  |
|  |           (ignore crate - respects .gitignore)             |  |
|  +-----------------------------------------------------------+  |
+-----------------------------------------------------------------+

Performance

Benchmarked on Apple M1 (criterion.rs):

Parsing Throughput

Search Latency

End-to-End Indexing

Key metrics:

• Tree-sitter parsing: ~2 GiB/s sustained throughput
• Symbol lookup: <1µs for exact match
• Full-text search: <1ms for most queries
• Hybrid search runs BM25 + TF-IDF in parallel via rayon

Development

# Run tests (359 tests)
cargo test

# Run benchmarks (criterion.rs)
cargo bench

# Run with debug logging
RUST_LOG=debug cargo run -- --repos ./test-fixtures

# Format code
cargo fmt

# Lint
cargo clippy

# Test with MCP Inspector
npx @modelcontextprotocol/inspector ./target/release/narsil-mcp --repos ./path/to/repo

Troubleshooting

Tree-sitter Build Errors

If you see errors about missing C compilers or tree-sitter during build:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt install build-essential

# For WASM builds
brew install emscripten  # macOS

Neural Search API Errors

# Check your API key is set
echo $VOYAGE_API_KEY  # or $OPENAI_API_KEY

# Common issue: wrong key format
export VOYAGE_API_KEY="pa-..."  # Voyage keys start with "pa-"
export OPENAI_API_KEY="sk-..."  # OpenAI keys start with "sk-"

Index Not Finding Files

# Check .gitignore isn't excluding files
narsil-mcp --repos /path --verbose  # Shows skipped files

# Force reindex
narsil-mcp --repos /path --reindex

Memory Issues with Large Repos

# For very large repos (>50K files), increase stack size
RUST_MIN_STACK=8388608 narsil-mcp --repos /path/to/huge-repo

# Or index specific subdirectories
narsil-mcp --repos /path/to/repo/src --repos /path/to/repo/lib

Roadmap

Completed

• Multi-language symbol extraction (16 languages)
• Full-text search with Tantivy (BM25 ranking)
• Hybrid search (BM25 + TF-IDF with RRF)
• AST-aware code chunking
• Git blame/history integration
• Call graph analysis with complexity metrics
• Control flow graph (CFG) analysis
• Data flow analysis (DFG) with reaching definitions
• Dead code and dead store detection
• Taint analysis for injection vulnerabilities
• Security rules engine (OWASP, CWE, crypto, secrets)
• SBOM generation (CycloneDX, SPDX)
• Dependency vulnerability checking (OSV)
• License compliance analysis
• Import graph with circular dependency detection
• Cross-language symbol resolution
• Incremental indexing with Merkle trees
• Index persistence
• Watch mode for file changes
• LSP integration
• Remote repository support
• Streaming responses

What's New

v1.1.x (Current)

• Multi-platform distribution - Install via Homebrew, Scoop, npm, Cargo, or direct download
• Configurable tool presets - Minimal, balanced, full, and security-focused presets
• Automatic editor detection - Optimal defaults for Zed, VS Code, Claude Desktop
• Interactive setup wizard - narsil-mcp config init for easy configuration
• Swift and Verilog support - Now supporting 16 languages
• Improved performance - Faster startup with background indexing

v1.0.x

• Neural semantic search - Find similar code using Voyage AI or OpenAI embeddings
• Type inference - Infer types in Python/JavaScript/TypeScript without external tools
• Multi-language taint analysis - Security scanning for PHP, Java, C#, Ruby, Kotlin
• WASM build - Run in browser for code playgrounds and educational tools
• 111 bundled security rules - OWASP, CWE, crypto, secrets detection
• IDE configs included - Claude Desktop, Cursor, VS Code, Zed templates

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Credits

Built with:

• tree-sitter - Incremental parsing
• tantivy - Full-text search
• tokio - Async runtime
• rayon - Data parallelism
• serde - Serialization