Narsil MCP服务器Docker镜像

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+

CRITICAL: Do NOT expose this container directly to the internet without proper security measures (reverse proxy, SSL/TLS, authentication, firewall rules).

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:

Security Warning: The container defaults to HTTP (ENABLE_HTTPS=false) for easier local setup. Use ENABLE_HTTPS=true with your own certificates for production. See CERTIFICATE_SETUP_GUIDE.md for instructions.

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

Boolean values: true, 1, yes, on are all accepted as truthy. Everything else is falsy.

Once per container lifecycle: NARSIL_REINDEX runs only once after the container is created. It is skipped on subsequent restarts (e.g., crash recovery, docker restart). To re-trigger, recreate the container (docker compose down && docker compose up -d).

Healthcheck: The container's healthcheck has a 450-second start period to accommodate the index-ready gate (see WAIT_FOR_INDEX below) plus initial indexing/model loading.

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