Narsil MCP
About
Blazingly fast 🔥 best in class MCP server in Rust 🦀 with neural engine, security profiling, and optional graph frontend
Details
- Author
- postrv
- Categories
- Developer Tools
Jump to
Setup
Install Narsil MCP in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/postrv/narsil-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
- Find symbols across 32 languages— Search for functions, classes, or interfaces by name or pattern usingfind_symbolsorworkspace_symbol_search.
- Trace tainted data for security audits— Follow user input through the codebase withtrace_taintand detect injection vulnerabilities like SQLi or XSS.
- Analyze function call relationships— Map callers, callees, and paths between functions withget_call_graph,get_callers, andfind_call_path.
- Generate a software bill of materials— Export a CycloneDX or SPDX SBOM and check dependencies against the OSV database withgenerate_sbomandcheck_dependencies.
- Infer types without external checkers— Get inferred types for Python, JavaScript, or TypeScript variables usinginfer_typesand find potential type errors.
- Query the codebase as a knowledge graph— Run SPARQL queries against the RDF graph or export tiered CCG layers for AI consumption withsparql_queryandexport_ccg.
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.
- 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
- 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
brew tap postrv/narsil brew install narsil-mcp
scoop bucket add narsil https://github.com/postrv/scoop-narsil scoop install narsil-mcp
npm install -g narsil-mcp # or yarn global add narsil-mcp # or pnpm add -g narsil-mcp
# 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
curl -fsSL https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.sh | bash
irm https://raw.githubusercontent.com/postrv/narsil-mcp/main/install.ps1 | iex
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.
- Rust 1.70 or later
- On Windows:Visual Studio Build Toolswith "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
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--graphCLI flag requires the binary to be built with--features graph. If you pass--graphto a binary built without this feature, you'll see a warning and SPARQL/CCG tools won't be available. SeeTroubleshootingbelow.
For detailed installation instructions, troubleshooting, and platform-specific guides, seedocs/INSTALL.md.
# 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
# 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
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, butonly 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:
If you pass--graphto 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
- 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)
v1.1.0+ introduces optional configurationfor fine-grained control over tools and performance.All existing usage continues to work- configuration is completely optional!
# 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
narsil-mcp detects your editor and applies an optimal preset automatically:
- Minimal preset:61% fewer tokens vs Full
- Balanced preset:25% fewer tokens vs Full
# 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
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.yamlin repo root):
version: "1.0" preset: "security-focused" # Override user preset tools: categories: Security: enabled: true SupplyChain: enabled: true
Named repository profilesare useful for multi-repo workspaces:
version: "1.0" profiles: platform: repos: - ~/src/api - ~/src/web git: true call_graph: true persist: true preset: balanced
narsil-mcp --profile platform narsil-mcp config profiles
Priority:CLI flags > Environment vars > Project config > User config > Defaults
# Select repos/profile export NARSIL_REPOS=~/src/api,~/src/web export NARSIL_PROFILE=platform # 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
# 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 # List named repository profiles narsil-mcp config profiles
- Configuration Guide- Full configuration reference
- Installation Guide- Platform-specific installation
Explore call graphs, imports, symbol references, and control flow 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
- Interactive Cytoscape.js graphs with drag, zoom, and double-click drill-down
- Complexity metrics overlay with color coding (green/yellow/orange/red)
- Security vulnerability overlay highlighting taint sources and sinks
- Six layout algorithms (dagre, force-directed, breadthfirst, concentric, circle, grid)
- File tree sidebar with syntax-highlighted code viewer
- URL-driven state (shareable links, browser back/forward)
- Dark mode support
- Node detail panel with code excerpts and navigation to source
Full documentation:Seedocs/frontend.mdfor setup, API endpoints, and development mode.
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:Seedocs/neural-search.mdfor setup, backends, and use cases.
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
For large-scale agentic workflows, narsil-mcp can be used throughForgemax— a Code Mode MCP gateway that collapses all 90 tools into just 2 (search+execute), reducing tool schema overhead from ~12,000 tokens to ~1,000.
# Install Forgemax cargo install forgemax # Run narsil-mcp through Forgemax (uses forge.toml in repo root) forgemax
The includedforge.tomlconfigures narsil-mcp with sensible defaults:
[servers.narsil] command = "narsil-mcp" args = ["--repos", ".", "--git", "--call-graph", "--persist", "--watch"] transport = "stdio" [sandbox] timeout_secs = 10 max_heap_mb = 64 max_concurrent = 8
The LLM writes JavaScript that calls through typed proxy objects inside a sandboxed V8 isolate — credentials, file paths, and internal state never leave the host. This approach is particularly useful when working with multiple MCP servers simultaneously, as it keeps the total tool context small and predictable.
Add narsil-mcp to your AI assistant by creating a configuration file. Here are the recommended setups:
Claude Code(.mcp.jsonin project root - Recommended):
Create.mcp.jsonin your project directory for per-project configuration:
{ "mcpServers": { "narsil-mcp": { "command": "narsil-mcp", "args": ["--repos", ".", "--git", "--call-graph"] } } }
Using.for--reposautomatically indexes the current directory. Claude now has access to 90 code intelligence tools.
Tip: Add--persist --index-path .claude/cachefor faster startup on subsequent runs.
For global configuration, edit~/.claude/settings.jsoninstead. SeeClaude Code Integrationfor advanced setups.
{ "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"] } } }
{ "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.
ForClaude Codeusers, we provide a plugin with slash commands and a skill for effective tool usage.
# Add the narsil-mcp marketplace /plugin marketplace add postrv/narsil-mcp # Install the plugin /plugin install narsil@narsil-mcp
/plugin install github:postrv/narsil-mcp/narsil-plugin
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
