SimBrain

简体中文 | English

SimBrain incrementally ingests local documents into Elasticsearch and provides MCP tools and CLIs for ingestion, project inspection, progress monitoring, and retrieval.

Quick start

SimBrain defaults to local Ollama at http://localhost:11434 with the bge-m3 model. Start Ollama and install the model first:

ollama pull bge-m3

Every usage mode requires Elasticsearch. At minimum, configure its endpoint and authentication:

ES_URL=https://your-es-host:9200
ES_API_KEY=your_es_api_key

See .env.example for all fields and defaults. When running from source, copy it to .env:

cp .env.example .env

MINERU_API_TOKEN is optional. When configured, MinerU is preferred for PDF parsing; otherwise SimBrain falls back to pypdf.

Supported document formats: PDF, DOCX, TXT, TEXT, Markdown, CSV, and XLSX.

Use with MCP

SimBrain exposes an MCP server over standard input/output (stdio). Once published on PyPI, start it with:

uvx --from simbrain simbrain-mcp

The server exposes these tools:

Tool	Arguments	Purpose
simbrain-ingest	input_dir, output_dir, project	Incremental ingestion
simbrain-status	output_dir	List all projects
simbrain-status-realtime	output_dir, project	Monitor ingestion progress
simbrain-search	question, project, top_k	Hybrid vector and keyword retrieval

Codex configuration

Add this to ~/.codex/config.toml:

[mcp_servers.simbrain]
command = "uvx"
args = ["--from", "simbrain", "simbrain-mcp"]

[mcp_servers.simbrain.env]
ES_URL = "https://your-es-host:9200"
ES_API_KEY = "your_es_api_key"
MINERU_API_TOKEN = "your_mineru_token"

Or register it from the command line:

codex mcp add simbrain \
  --env ES_URL=https://your-es-host:9200 \
  --env ES_API_KEY=your_es_api_key \
  --env MINERU_API_TOKEN=your_mineru_token \
  -- uvx --from simbrain simbrain-mcp

Claude Desktop configuration

Add this entry under mcpServers in claude_desktop_config.json:

{
  "simbrain": {
    "command": "uvx",
    "args": ["--from", "simbrain", "simbrain-mcp"],
    "env": {
      "ES_URL": "https://your-es-host:9200",
      "ES_API_KEY": "your_es_api_key",
      "MINERU_API_TOKEN": "your_mineru_token"
    }
  }
}

Remove MINERU_API_TOKEN if MinerU is not needed. All remaining settings use the defaults from .env.example. To use an OpenAI-compatible embedding service, set EMBEDDING_PROVIDER, EMBEDDING_URL, EMBEDDING_API_KEY, and EMBEDDING_MODEL together.

Use with the CLI

The examples below use the PyPI package. When developing this repository, replace uvx --from simbrain with uv run.

Incremental ingestion

uvx --from simbrain simbrain-ingest \
  --input-dir ./docs \
  --output-dir ./output \
  --project my-knowledge-base

Files with the same name are updated, unchanged files are skipped, and historical files omitted from the current input are retained.

List all projects

uvx --from simbrain simbrain-status --output-dir ./output

Monitor ingestion progress

uvx --from simbrain simbrain-status \
  --output-dir ./output \
  --project my-knowledge-base

Search a project

uvx --from simbrain simbrain-search \
  --question "How do I configure access permissions?" \
  --project my-knowledge-base \
  --top-k 10

top-k must be between 1 and 100. Results contain source chunks and metadata; SimBrain does not generate an LLM answer.

Output and tests

Successful CLI calls return JSON. The progress command emits JSON Lines when its state changes.

Run tests:

uv run pytest -q

To include the Elasticsearch integration test:

SIMBRAIN_TEST_ES_URL=http://localhost:9200 uv run pytest -q -m integration