OpenContextEngine

Name: OpenContextEngine
Author: Wenchao An

Self-hosted code retrieval over MCP, using your own embedding and reranking endpoints

By Wenchao An (individual) TypeScript Local · stdio Developer tools

GitHub npm Website

33 popularity score ★ 55 ↓ 27/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio

Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.

Or add it by command or config

It needs EMBEDDING_BASE_URL, EMBEDDING_API_KEY, EMBEDDING_MODEL, RERANK_BASE_URL, RERANK_API_KEY, RERANK_MODEL. Replace each <NAME> with your value.

FirstTerminal

npm install -g open-context-engine
open-context-engine setup

Claude CodeTerminal

claude mcp add opencontextengine -e EMBEDDING_BASE_URL=<EMBEDDING_BASE_URL> -e EMBEDDING_API_KEY=<EMBEDDING_API_KEY> -e EMBEDDING_MODEL=<EMBEDDING_MODEL> -e RERANK_BASE_URL=<RERANK_BASE_URL> -e RERANK_API_KEY=<RERANK_API_KEY> -e RERANK_MODEL=<RERANK_MODEL> -- open-context-engine mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "opencontextengine": {
      "command": "open-context-engine",
      "args": [
        "mcp"
      ],
      "env": {
        "EMBEDDING_BASE_URL": "<EMBEDDING_BASE_URL>",
        "EMBEDDING_API_KEY": "<EMBEDDING_API_KEY>",
        "EMBEDDING_MODEL": "<EMBEDDING_MODEL>",
        "RERANK_BASE_URL": "<RERANK_BASE_URL>",
        "RERANK_API_KEY": "<RERANK_API_KEY>",
        "RERANK_MODEL": "<RERANK_MODEL>"
      }
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "opencontextengine": {
      "command": "open-context-engine",
      "args": [
        "mcp"
      ],
      "env": {
        "EMBEDDING_BASE_URL": "<EMBEDDING_BASE_URL>",
        "EMBEDDING_API_KEY": "<EMBEDDING_API_KEY>",
        "EMBEDDING_MODEL": "<EMBEDDING_MODEL>",
        "RERANK_BASE_URL": "<RERANK_BASE_URL>",
        "RERANK_API_KEY": "<RERANK_API_KEY>",
        "RERANK_MODEL": "<RERANK_MODEL>"
      }
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "opencontextengine": {
      "type": "stdio",
      "command": "open-context-engine",
      "args": [
        "mcp"
      ],
      "env": {
        "EMBEDDING_BASE_URL": "<EMBEDDING_BASE_URL>",
        "EMBEDDING_API_KEY": "<EMBEDDING_API_KEY>",
        "EMBEDDING_MODEL": "<EMBEDDING_MODEL>",
        "RERANK_BASE_URL": "<RERANK_BASE_URL>",
        "RERANK_API_KEY": "<RERANK_API_KEY>",
        "RERANK_MODEL": "<RERANK_MODEL>"
      }
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.opencontextengine]
command = "open-context-engine"
args = ["mcp"]

[mcp_servers.opencontextengine.env]
EMBEDDING_BASE_URL = "<EMBEDDING_BASE_URL>"
EMBEDDING_API_KEY = "<EMBEDDING_API_KEY>"
EMBEDDING_MODEL = "<EMBEDDING_MODEL>"
RERANK_BASE_URL = "<RERANK_BASE_URL>"
RERANK_API_KEY = "<RERANK_API_KEY>"
RERANK_MODEL = "<RERANK_MODEL>"

Gemini CLITerminal

gemini mcp add --scope user -e EMBEDDING_BASE_URL=<EMBEDDING_BASE_URL> -e EMBEDDING_API_KEY=<EMBEDDING_API_KEY> -e EMBEDDING_MODEL=<EMBEDDING_MODEL> -e RERANK_BASE_URL=<RERANK_BASE_URL> -e RERANK_API_KEY=<RERANK_API_KEY> -e RERANK_MODEL=<RERANK_MODEL> opencontextengine open-context-engine -- mcp

Settings 12

`EMBEDDING_BASE_URL`	Required: HTTPS base URL of the embedding service; may instead be saved by `setup`.
`EMBEDDING_API_KEY`	Required: Key for the embedding service; may instead be saved by `setup`.
`EMBEDDING_MODEL`	Required: Embedding model name, e.g. Qwen3-Embedding-4B; may instead be saved by `setup`.
`RERANK_BASE_URL`	Required: HTTPS base URL of the reranking service; may instead be saved by `setup`.
`RERANK_API_KEY`	Required: Key for the reranking service; may instead be saved by `setup`.
`RERANK_MODEL`	Required: Reranking model name, e.g. Qwen3-Reranker-4B; may instead be saved by `setup`.
`OCE_EMBEDDING_DIMENSIONS`	Optional: Output size of the embedding model; must match the endpoint.
`OCE_RERANK_API`	Optional: Rerank API style: rerank (default), dashscope or rerank-batch.
`OCE_EMBEDDING_CONCURRENCY`	Optional: Parallel embedding requests while indexing, 1-8, default 1.
`OCE_EXCLUDE`	Optional: JSON array of glob patterns to leave out of the index.
`OCE_MAX_FILES`	Optional: Maximum files per workspace, default 50,000.
`OCE_CONFIG_HOME`	Optional: Alternative directory for saved settings and Python runtimes.

What it does

OpenContextEngine indexes a local repository and answers natural-language questions about it with source snippets, file paths and line numbers. It combines vector search (through an embedding service you configure), keyword search, links between code units, and a reranking service. The result is trimmed to a token budget so a coding agent can find where a behaviour is implemented without reading files one by one.

The agent passes the project's absolute path with each call. The first request starts indexing in the background, and later calls reuse that index. A background worker follows saved edits, deletions and branch switches, and re-embeds only changed content. Python, TypeScript, JavaScript and Go get language-aware parsing; other text files are indexed as plain text. Overlapping parent and child workspaces share cached text and embeddings from version 0.1.10.

The v0.1.10 source (src/mcp.mjs) registers two tools, both marked read-only. search_code returns up to 8,000 tokens by default; `budget` can lower that to as little as 256 but cannot raise it. A query is capped at 8,192 characters. index_status lists coverage 50 entries per page by default, up to 200 with `limit`. Starting it with `--root` pins it to one repository and rejects any other path.

What it needs

Runtime	Node.js 22+

Node.js 22.14+, Python 3.10+ (with venv and pip) and Git, on macOS, Linux or Windows (native Windows from 0.1.3). Go 1.22+ is needed only to analyse Go code. You need an HTTPS embedding service that implements /v1/embeddings and a reranking service, each with its URL, key and model name. Run `open-context-engine setup` once: it creates a Python environment and needs network access to npm and PyPI.

Limits

Indexing and search depend on your external embedding and reranking services. The makers evaluated only Qwen3 4B models; other models need your own testing. Plain HTTP endpoints are refused unless OCE_ALLOW_HTTP=1, and local model endpoints are not allowed. Unsaved editor buffers, Git-ignored files, dependencies, build output, binary files and symlinks are not indexed. Default caps are 50,000 files and 256 MiB of source per workspace. Going over a cap fails the index rather than publishing a partial one. Changing the model, provider or dimensions forces a rebuild. While indexing is in progress, search reports that the index is updating instead of returning results.

Who it suits

It suits developers using Codex, Claude Code or another stdio MCP client on medium or large repositories, where an agent struggles to find related code with plain text search. You must be able to point it at paid or self-hosted embedding and reranking APIs and accept that code fragments are sent to them. If code must stay entirely on your machine with no model services, or you want a tool that needs no setup, a grep-style or language-server tool is a better fit. It only reads and indexes code. It does not edit files or run commands.

Tools 2

search_code: Finds code related to a plain-language task in a project and returns ranked snippets with paths and line numbers, within a token budget
index_status: Reports a project's index sync state, update errors and which files or folders are indexed, excluded or pending

Popularity

33 popularity score

★ 55 ↓ 27/wk

GitHub stars	55	21 points
npm downloads, last week	27	11.6 points

Measured 2026-11-07. How the score works.

Where it is published

Code	annasusu/opencontextengine ★ 55
npm	open-context-engine 0.1.10, 2026-10-12

What it can reach

Runs	On your machine
Reaches	Files on your machine, The internet
Changes things	No: it reads only
Sign-in	An API key or token
Licence	MIT (npm)
Last code change	2026-10-12

It reads source files in the project directories the agent names, or only the one given with --root. Code fragments and queries are sent to the embedding and reranking endpoints you configure, so they leave your machine unless those services are self-hosted. HTTPS is required unless OCE_ALLOW_HTTP=1 is set. Both tools are marked read-only and do not change project files. The server does write its own index, source copies and embeddings under ~/.cache/opencontextengine/, and keeps API keys in ~/.config/opencontextengine/config.json, which has owner-only permissions on macOS and Linux. A local worker uses an access token stored in worker.json. The .env file of a searched project is never loaded.

Over time

GitHub stars 55 +3 (+6 %)

5551

13 Oct 20267 Nov 2026

npm downloads a week 27 −794 (−97 %)

8210

12 Oct 20267 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 33 −10 (−24 %)

4421

13 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-10-14.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![OpenContextEngine on EveryMCPServer](https://everymcpserver.com/badge/opencontextengine.svg)](https://everymcpserver.com/servers/opencontextengine)

Connect your client

Add in one click

Or add it by command or config

Settings 12

What it does

What it needs

Limits

Who it suits

Tools 2

Similar servers

autocontext

jDocMunch MCP

opencode-mcp

Quill

OpenLore

Ref MCP