Skip to main content
Glama
Kimono MCP Server

Kimono MCP Server

by lcalmejane

Kimono RAG MCP

Version française

Local RAG for your code and documentation. Kimono indexes a project on your machine and gives MCP-compatible assistants lexical and semantic search. It returns relevant files and line ranges first, so an assistant can retrieve specific passages instead of loading whole files.

In the current Copilot benchmark, Kimono RAG measured lower cumulative input and shorter elapsed time than standard Copilot search on both tested tasks:

Task

Cumulative input

Elapsed time

Indexing and ignore-policy research

323,368 → 105,223 tokens (−67.5%)

111.212 → 79.077 s (−28.9%)

Prepare a maxDepth implementation plan

454,796 → 130,244 tokens (−71.4%)

175.224 → 84.034 s (−52.0%)

The benchmark used Gemini 3.8 Flash in Copilot CLI 1.0.103. Kimono searched locally and read selected line ranges. See the benchmark results. Indexing and embeddings run locally; the client may send retrieved passages to its configured model provider.

Semantic indexing uses bounded vector batches and balanced short/long batch scheduling. Static code and multilingual models use the Rust CPU backend with shared memory-mapped tables, without ONNX startup. Auto balanced combines static code embeddings with E5 for documents; Auto speed uses static models for both. Model downloads and policy changes require separate confirmations. For ONNX models, Kimono compares CPU and available CUDA/CoreML providers and reuses the fastest measured provider for that session. See models, runtime selection and memory settings.

Choose how to use Kimono

To identify the running server, call aikido_root with {"operation":"status"}. Its server field contains Kimono's package name and version, distinct from the embedding engine version and corpus fingerprint. The MCP initialization response and authenticated HTTP /statusz and /readyz endpoints report the same server identity.

Use

Best for

Setup

IDE extension — recommended

VS Code and IDEs that support Visual Studio Marketplace extensions

Install from the Visual Studio Marketplace. The extension includes the runtime and search engines.

Docker server

A shared project corpus for multiple MCP clients, including GitHub Copilot cloud agent

Run the published GHCR image or build with Docker Compose, then connect MCP clients to its /mcp endpoint.

Native install from source

A local server for an MCP client that supports stdio

Build the server and native engines, then configure the MCP client to launch the server.

VS Code-based IDEs can also use the extension when they support Visual Studio Marketplace extensions. Availability depends on each IDE's extension and Marketplace configuration.

Direct integrations for LLM CLIs (Claude Code, Codex and others) are planned. For now, use an MCP-compatible client with the Docker HTTP server or the native stdio installation.

Related MCP server: andish-mcp

Install the extension in VS Code and compatible IDEs

  1. Install Kimono RAG MCP from the Visual Studio Marketplace.

  2. Open and trust the project folder.

  3. In VS Code, run MCP: List Servers, start Kimono, and enable its tools in your chat client's tool picker.

  4. Use the Kimono management panel to view indexing progress and change the project folder or corpus settings.

Requires VS Code 1.106 or newer and a chat client that supports MCP.

Manual VSIX installation

Download the VSIX for the extension host platform from GitHub Releases:

Extension host

Package

macOS Apple Silicon

darwin-arm64

macOS Intel

darwin-x64

Linux ARM64 (glibc)

linux-arm64

Linux Intel/AMD 64-bit (glibc)

linux-x64

Windows Intel/AMD 64-bit

win32-x64

In VS Code, run Extensions: Install from VSIX… and choose the downloaded file. For Remote SSH, WSL or Dev Containers, install the extension on the remote extension host. The package includes Node.js and the local search components; no separate runtime installation is required.

Run a shared Docker Compose server

Use Docker Compose when several MCP clients need the same indexed project. Install Docker Engine with the Compose plugin, then from this repository:

cp .env.example .env
mkdir -p data/project

Put the project to index in data/project. In .env, configure:

AIKIDO_HOST_PARENT=./data
AIKIDO_DIR=project
KIMONO_CORPUS_MODE=rag
AIKIDO_VOLUME_MODE=ro
MCP_AUTH_TOKEN=replace-with-a-long-random-token

Generate a token, for example with openssl rand -hex 32, and keep .env private. Start the server:

docker compose up --build -d

The MCP endpoint is http://127.0.0.1:3000/mcp. Configure each client to use the Streamable HTTP transport and send the bearer token. The default Compose configuration listens on the local machine only. For access from other machines, use TLS and an authenticated reverse proxy; do not expose the unauthenticated container port to the Internet.

To use the published container image instead of building it locally, pull the image and run it with the same settings and mounted project directory:

export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
docker pull ghcr.io/lcalmejane/kimono-mcp-server:latest
docker run --rm \
  -p 127.0.0.1:3000:3000 \
  -e AIKIDO_ROOT=/workspace \
  -e KIMONO_CORPUS_MODE=rag \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=3000 \
  -e MCP_AUTH_TOKEN="$MCP_AUTH_TOKEN" \
  -v "$PWD:/workspace:ro" \
  -v kimono-cache:/home/node/.cache/kimono \
  ghcr.io/lcalmejane/kimono-mcp-server:latest

The image is published to the GitHub Container Registry for Linux AMD64 and ARM64. Each v* version tag runs the container publishing workflow, which publishes a matching version tag (for example, v0.6.4) and updates latest. Use a version tag when you want to pin a deployment; use latest to follow the most recently published version. Docker Compose remains the simpler option for persistent local service management.

Connect GitHub Copilot cloud agent

The GHCR package is a container image, not a running MCP endpoint. To use it with GitHub Copilot cloud agent, deploy the image on a host reachable by GitHub over HTTPS, configure it to serve HTTP MCP, and mount or synchronize the repository that Kimono should index. The server's AIKIDO_ROOT must point to that accessible checkout; a remote server does not automatically see the agent's temporary repository workspace.

In the repository's Settings → Copilot → coding agent → MCP configuration, add a remote server entry. Store the bearer token as an Agents secret named COPILOT_MCP_AUTH_TOKEN:

{
  "mcpServers": {
    "kimono": {
      "type": "http",
      "url": "https://kimono.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${COPILOT_MCP_AUTH_TOKEN}"
      },
      "tools": ["aikido_snapshot", "aikido_search", "aikido_file", "aikido_structure", "aikido_index"]
    }
  }
}

The endpoint must be reachable from GitHub and protected with HTTPS and authentication. Local Docker Compose binds to loopback and is not directly reachable by GitHub's cloud agent. See GitHub's repository MCP server configuration guide and the local RAG guide for server setup and corpus configuration.

To use AI-KIDO mode instead, set KIMONO_CORPUS_MODE=aikido and choose a ROOT containing prompts/index.md or index.md. For an existing AI-KIDO checkout, set AIKIDO_DIR to its folder name under AIKIDO_HOST_PARENT.

Build and run the native server from source

To run Kimono without Docker, build the server and native engines from source. Linux x64 example; choose a matching platform target as described in the native bundle guide:

npm ci
npm run build
npm run bundle:native -- --target linux-x64 --output native-bundles/linux-x64

Set the environment using the paths in the native bundle's manifest.json, then launch the stdio server with the project ROOT:

export FGR_BIN="$PWD/native-bundles/linux-x64/bin/fgr"
export KIMONO_SEMANTIC_BIN="$PWD/native-bundles/linux-x64/bin/kimono-semantic"
export KIMONO_MODEL_DIR="$PWD/native-bundles/linux-x64/model"
export ORT_DYLIB_PATH="$PWD/native-bundles/linux-x64/lib/libonnxruntime.so"
AIKIDO_ROOT=/absolute/path/to/project \
KIMONO_CORPUS_MODE=rag \
node dist/cli.js serve

Configure the MCP client to launch this command with the same environment. Platform targets, ONNX libraries and environment variables are documented in the native bundle guide. To share one index among clients, use the Docker HTTP server.

Use RAG

RAG is the default and works with ordinary source-code and documentation projects; no special project structure is required.

  1. Select Kimono's MCP tools in the client.

  2. Ask the assistant to search the project for the relevant files or concepts.

  3. Let it read the returned line ranges when it needs the source details.

Search uses lexical and semantic retrieval. Results identify files and lines before any source content is read. .gitignore rules apply; common dependency, build and cache folders are excluded. Kimono does not modify project files.

Office documents, PDF and file metadata

RAG also extracts text from Excel .xlsx, Word .docx, PowerPoint .pptx and PDF documents. Excel results retain worksheet names and cell addresses, for example Costs!A5=Budget | B5=42. Word results follow paragraph order, including table cells. PowerPoint text follows presentation slide order, including table cells, with slide numbers (Slide 1: …). Speaker notes and text inside images are not extracted. Search line numbers refer to the extracted text, not the document's page layout. Formulas use their saved result when available; Kimono does not run formulas or macros.

PDF extraction uses pdftotext from Poppler. Docker includes it; for native or embedded extension use, install Poppler separately (brew install poppler on macOS, sudo apt-get install poppler-utils on Debian/Ubuntu) and make pdftotext available on the server's PATH. Scanned PDFs are not OCR-processed.

Files remain discoverable even when their contents cannot be read. For unsupported formats, binary, oversized, unreadable or failed-extraction files, Kimono indexes the filename, ROOT-relative path, extension, size and last modification date when available. Results explicitly identify contentStatus: "metadata-only" and explain the missing content. This also applies when PDF extraction is unavailable. Original files are never replaced with extracted text or metadata.

.gitignore, include/exclude rules and built-in safety exclusions still apply to file metadata. Use path exclusions to remove a file entirely; an extension allowlist controls content extraction, not the RAG file catalog.

Configure the corpus

In VS Code, use Kimono: Open Management Panel or set:

Setting

Default

Purpose

kimono.corpusMode

rag

rag for ordinary projects; aikido for an AI-KIDO knowledge base.

kimono.root

Open workspace folder

Folder to index.

kimono.mode

embedded

embedded for a local server, remote for an existing HTTP MCP server, or disabled.

kimono.url

Empty

Remote server's HTTPS /mcp URL when kimono.mode is remote.

kimono.configFile

Empty

Optional absolute path to a host-managed corpus configuration.

For VS Code settings, see the extension guide. Remote bearer tokens are entered through Kimono: Set Remote Token and stored in VS Code SecretStorage.

For server installations, KIMONO_CORPUS_MODE selects the mode and AIKIDO_ROOT selects the project directory. An optional JSON config can narrow file types or paths and adjust corpus limits:

{
  "mode": "rag",
  "extensions": [".md", ".ts", ".tsx", ".js", ".py"],
  "include": ["src/**", "docs/**"],
  "exclude": ["**/*.generated.*", "**/fixtures/**"]
}

Configuration paths are chosen by the server host; project files are not loaded as configuration automatically. The defaults limit a corpus to 100,000 files and 512 MiB, with a 4 MiB maximum file size in RAG mode. See the RAG setup guide for all settings and limits.

Projects with several Git repositories

A project can hold independent Git repositories inside ROOT (for example a frontend or an MCP server versioned separately). When the ROOT .gitignore ignores them, Kimono skips them, as Git does. Declare them in repositories, in the corpus config or in the project policy (KIMONO_PROJECT_POLICY_FILE, next to gitUrl):

{
  "repositories": [
    { "path": "", "gitUrl": "https://github.com/acme/platform.git" },
    { "path": "web-agent", "name": "agent", "gitUrl": "https://github.com/acme/agent.git", "branch": "main" },
    { "path": "mcp-server" }
  ]
}
  • path is ROOT-relative ("" is ROOT). name defaults to the last path segment (root for ROOT).

  • A declared repository is indexed even when the parent ignores it, under its own .gitignore files only.

  • aikido_search takes repository (name or path); root means ROOT without its declared repositories.

  • aikido_git infos lists each declared repository's HEAD, branch and status. A commit or edit inside one invalidates the index basis like a change in ROOT.

  • Hosts can also pass the list as JSON in KIMONO_REPOSITORIES (added to the config file's list). In VS Code, set kimono.repositories per folder, or enter the paths in the management panel.

  • The single gitUrl of the policy still describes ROOT. Remote sync still clones ROOT only.

Optional AI-KIDO mode

Kimono can also retrieve an existing AI-KIDO knowledge base when you select aikido mode. It keeps local RAG available for any project and adds AI-KIDO-specific knowledge discovery and collaboration when needed. Learn more about the wider method and tools at www.ai-kido.fr.

More help

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables interaction with a local knowledge repository via MCP, providing tools for capturing, indexing, and searching Markdown notes with Git version control and optional semantic search.
      4 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP-compatible clients to search and query a team knowledge graph, retrieve document context, upload files for indexing, explore entities and connections, and monitor workspace usage and server health.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables to build and query a knowledge base with retrieval-augmented generation, supporting document ingestion, hybrid search, and live data integration from external APIs via MCP tools.
      2
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables authenticated MCP clients to manage versioned research documents, work items, and immutable notes, and to run scheduled static security audits over selected GitHub repositories through a configured AI provider.
      AGPL 3.0