Narsil MCP

🚀 narsil-mcp

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

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

🚀 Quick Start

narsil-mcp is a high - performance MCP server. You can quickly start using it by following the installation and usage steps below.

✨ Features

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.

📦 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

⚠️ Important 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

💡 Usage Tip

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

💻 Usage Examples

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

⚠️ Important 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

💡 Usage Tip

• 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.

💡 Usage Tip

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.

💡 Usage Tip

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.

💡 Usage 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"]
    }
  }
}

⚠️ Important 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"]
    }
  }
}

⚠️ Important 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');

💡 Usage Tip

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

📚 Documentation

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

🔧 Technical Details

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

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