mekayelanik/narsil-mcp repository overview

⁠Narsil MCP Server - Docker Image

Unofficial Multi-Architecture Docker Image for Narsil MCP Server

⁠Overview

This is an unofficial, community-maintained Docker image that packages the Narsil MCP Server⁠ for containerized deployment. It enables AI agents (Claude Code, VS Code Copilot, Cursor, Windsurf, etc.) to perform deep code intelligence via the Model Context Protocol (MCP).

Upstream: github.com/postrv/narsil-mcp⁠ (MIT OR Apache-2.0)

⁠Key Features

• Multi-Architecture Support - Native support for x86-64 and ARM64
• Modern MCP Bridge - mcp-proxy⁠ stdio↔StreamableHTTP/SSE; stateful, one shared child per session (no spawn-per-request leak)
• 90 Code Intelligence Tools - Symbol search, call graphs, security analysis, SBOM, and more
• 32 Language Support - Rust, Python, TypeScript, Go, Java, C#, and 26 more via Tree-sitter
• Secure by Design - API key auth (case-insensitive Bearer), CORS, TLS termination, security headers
• High Performance - HAProxy with QUIC/HTTP3 support, ZSTD compression

⁠Available Narsil MCP Tool Categories

⁠Buy Me a Coffee

Your support encourages me to keep creating/supporting my open-source projects. If you found value in this project, you can buy me a coffee to keep me inspired.

⁠

⁠Quick Start

⁠Prerequisites

• Docker Engine: 23.0+

⁠Docker Compose (Recommended)

services:
  narsil-mcp:
    image: mekayelanik/narsil-mcp:latest
    container_name: narsil-mcp
    restart: unless-stopped
    ports:
      - "8010:8010"
      # Optional: HTTP visualization frontend (requires NARSIL_HTTP=true)
      # - "3000:3000"
    volumes:
      - /path/to/your/repos:/data:ro
      - narsil-cache:/home/narsil/.cache         # Persist embedding model cache
    environment:
      - PORT=8010
      - INTERNAL_PORT=38011
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - NODE_ENV=production
      - PROTOCOL=SHTTP
      - ENABLE_HTTPS=false
      - HTTP_VERSION_MODE=auto
      - DATA_DIR=/data
      - NARSIL_GIT=true
      - NARSIL_CALL_GRAPH=true
      - NARSIL_PERSIST=true
      - NARSIL_STREAMING=true
      # Optional: Neural semantic search
      # - NARSIL_NEURAL=true
      # - VOYAGE_API_KEY=your-voyage-key
      # Optional: HTTP visualization frontend
      # - NARSIL_HTTP=true
      # - NARSIL_HTTP_PORT=3000
      # Optional: require Bearer token auth at HAProxy layer
      # - API_KEY=replace-with-strong-secret
      # Optional: CORS origins
      # - CORS=*

volumes:
  narsil-cache:
    driver: local

⁠Docker Run

docker volume create narsil-cache
docker run -d \
  --name=narsil-mcp \
  --restart=unless-stopped \
  -p 8010:8010 \
  -v /path/to/your/repos:/data:ro \
  -v narsil-cache:/home/narsil/.cache \
  -e PORT=8010 \
  -e PROTOCOL=SHTTP \
  -e NARSIL_GIT=true \
  -e NARSIL_CALL_GRAPH=true \
  -e NARSIL_PERSIST=true \
  mekayelanik/narsil-mcp:latest

# With HTTP visualization frontend enabled:
docker volume create narsil-cache
docker run -d \
  --name=narsil-mcp \
  --restart=unless-stopped \
  -p 8010:8010 \
  -p 3000:3000 \
  -v /path/to/your/repos:/data:ro \
  -v narsil-cache:/home/narsil/.cache \
  -e PORT=8010 \
  -e PROTOCOL=SHTTP \
  -e NARSIL_GIT=true \
  -e NARSIL_CALL_GRAPH=true \
  -e NARSIL_PERSIST=true \
  -e NARSIL_HTTP=true \
  mekayelanik/narsil-mcp:latest

⁠Access Endpoints

When HTTPS is enabled (ENABLE_HTTPS=true), use TLS endpoints:

⁠Configuration

⁠Complete Environment Variables Reference

⁠Core Settings

⁠Narsil MCP Feature Flags

⁠Narsil MCP String Settings

⁠Neural Embedding API Keys

⁠Neural Embedding Notes

Neural embeddings are optional. Without NARSIL_NEURAL=true, all 80+ core tools work (symbol search, call graphs, security scanning, SBOM, git analysis, type inference, data flow, SPARQL, etc.). Only neural_search and find_semantic_clones require embeddings.

• API backend (default): Set NARSIL_NEURAL=true + NARSIL_NEURAL_BACKEND=api + an API key. Default model is voyage-code-2 (1024 dims).
• ONNX backend (local, no API key): Set NARSIL_NEURAL_BACKEND=onnx. Requires manually downloading the model via optimum-cli export onnx. Does not auto-download.
• Cache persistence: The narsil-cache volume at /home/narsil/.cache persists model files and ONNX caches across restarts.

API backend examples:

# Voyage AI
- NARSIL_NEURAL=true
- NARSIL_NEURAL_BACKEND=api
- NARSIL_NEURAL_MODEL=voyage-code-2
- VOYAGE_API_KEY=your-voyage-key

# OpenAI
- NARSIL_NEURAL=true
- NARSIL_NEURAL_BACKEND=api
- NARSIL_NEURAL_MODEL=text-embedding-3-small
- OPENAI_API_KEY=sk-your-key

# Custom OpenAI-compatible endpoint (e.g., self-hosted embedding server)
- NARSIL_NEURAL=true
- NARSIL_NEURAL_BACKEND=api
- NARSIL_NEURAL_MODEL=Snowflake/snowflake-arctic-embed-xs
- EMBEDDING_SERVER_ENDPOINT=http://your-embedder-host:port/v1
- EMBEDDING_API_KEY=your-key-or-unused
- NARSIL_NEURAL_DIMENSION=384

⁠Narsil MCP Presets

⁠Security Settings

⁠Gateway & Startup Lifecycle

⁠API Key Authentication Notes

• Set API_KEY to enforce auth at the reverse proxy level.
• Header: Authorization: Bearer <API_KEY>.
• /healthz and CORS preflight (OPTIONS) bypass authentication.

⁠Rate Limiting and IP Access Control

• Rate limiting: Set RATE_LIMIT=100 to allow 100 requests per RATE_LIMIT_PERIOD (default 10s) per IP. Exceeding the limit returns HTTP 429 with a Retry-After header.
• Connection limiting: Set MAX_CONNECTIONS_PER_IP=50 to cap concurrent connections per IP. Exceeding returns HTTP 429.
• IP blocklist: Set IP_BLOCKLIST=192.0.2.0/24,198.51.100.5 to block specific IPs/CIDRs. Blocked IPs receive HTTP 403.
• IP allowlist: Set IP_ALLOWLIST=10.0.0.0/8,192.168.1.0/24 to allow only listed IPs/CIDRs. All others receive HTTP 403. Localhost is always allowed.
• All features default to disabled. Combine as needed — blocklist is checked before allowlist.

⁠One-Shot Operations

For ad-hoc operations without setting env vars, use docker exec:

docker exec narsil-mcp narsil-mcp --repos /data --reindex   # Force full re-index

⁠Mounting Repositories for Analysis

Mount your repository directories to /data (or the path specified by DATA_DIR). Each subdirectory becomes an indexable repository.

volumes:
  # Mount entire projects directory
  - /home/user/projects:/data:ro
  # Or mount individual repositories
  - /home/user/my-rust-app:/data/my-rust-app:ro
  - /home/user/my-node-app:/data/my-node-app:ro

Then tell your AI agent to analyze using the mounted path:

• "Search for symbols in /data/my-rust-app"
• "Find injection vulnerabilities in /data/my-node-app"
• "Generate an SBOM for /data/my-rust-app"
• "Get the call graph for main in /data/my-node-app"

⁠MCP Client Configuration

⁠Claude Code

Add to ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "narsil": {
      "type": "sse",
      "url": "http://host-ip:8010/sse"
    }
  }
}

Or for Streamable HTTP:

{
  "mcpServers": {
    "narsil": {
      "type": "http",
      "url": "http://host-ip:8010/mcp"
    }
  }
}

⁠VS Code / Codex / Cursor / Windsurf

All use the same JSON format. Configure in the respective config file:

• VS Code: .vscode/settings.json (key: mcp.servers)
• Codex: ~/.codex/config.json (key: mcpServers)
• Cursor: ~/.cursor/mcp.json (key: mcpServers)
• Windsurf: .codeium/mcp_settings.json (key: mcpServers)

{
  "mcpServers": {
    "narsil": {
      "transport": "http",
      "url": "http://host-ip:8010/mcp"
    }
  }
}

⁠Available Tags

⁠License

This Docker image packaging is licensed under the GNU General Public License v3.0⁠.

⁠Upstream Licenses

• Narsil MCP Server: MIT License⁠ OR Apache License 2.0⁠ - Copyright (c) 2024 postrv
• mcp-proxy⁠: MIT License (stdio↔SHTTP/SSE bridge; replaces supergateway)
• HAProxy: GNU General Public License v2.0

This is an unofficial community packaging. It is NOT affiliated with, endorsed by, or supported by the narsil-mcp authors. See NOTICE⁠ for full attribution.

⁠Buy Me a Coffee

Your support encourages me to keep creating/supporting my open-source projects. If you found value in this project, you can buy me a coffee to keep me inspired.

⁠

⁠Maintainer

Mohammad Mekayel Anik

• Docker Hub: mekayelanik⁠
• GitHub: MekayelAnik⁠