How do I use io.github.Brightdotdev/darwin-rag?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@io.github.Brightdotdev/darwin-rag Search the knowledge base for the incident response runbook and summarize the steps." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

io.github.Brightdotdev/darwin-rag

Official

by Brightdotdev

Overview Schema Source Related Servers Score Discussions Admin

Python

Hybrid

Darwin RAG

A local-first RAG engine that ingests documents, indexes them with BM25 + dense embeddings, and exposes search via an MCP server for AI agent integration.

Ingestion — PDF, Markdown, HTML, images (OCR), CSV, Excel, ODS, URLs
Indexing — BM25 keyword + dense embedding hybrid index with configurable chunking strategies
Search — Hybrid, semantic, or keyword retrieval with reranking, diversity rerank, and structural penalties
Generation — LLM-backed answer synthesis via LiteLLM (OpenAI, Anthropic, Gemini, etc.)
Observability — Structured logging with per-session history, queryable via MCP
Isolation — Multiple independent stores for tenant/project separation
Deployment — stdio (AI agent subprocess), SSE, or Streamable HTTP; Docker-ready
Local-first — Everything runs locally, fully offline-capable after setup

Built by BrightDotDev.
License: MIT with Attribution

Quick Start

1. Install

pip install darwin-rag

2. Set up models

# Interactive — detects hardware, pick your models
darwin-admin setup interactive

# Or one-shot (embedding-only, no prompts)
darwin-admin setup --preset required

3. Start the MCP server & connect

# stdio mode — for AI agent subprocess (Claude Desktop, Cursor, etc.)
darwin mcp

# Or HTTP mode — for remote clients
darwin mcp --http --port 8765

Configure your MCP client:

{
  "mcpServers": {
    "darwin": {
      "command": "darwin",
      "args": ["mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-..."  // At least one LLM provider key
      }
    }
  }
}

Or generate config automatically:

darwin config claude          # Claude Desktop config
darwin config cursor          # Cursor config
darwin config all --copy      # All clients + copy to clipboard

Related MCP server: Corpus-KB

MCP Tools

Tool	Description
`search_darwin`	Query the knowledge base with hybrid/semantic/keyword search
`search_lists`	Search structured data (CSVs, JSON arrays) by field values
`get_search_results`	List saved search results
`get_search_result_by_id`	Load a saved search result by filename
`get_schema`	Inspect schemas for structured files (keys, types, record counts)
`run_pipeline`	Ingest + index documents from a path or URL
`purge_artifacts`	Delete pipeline artifacts for specific files
`create_store`	Create a new isolated data store
`list_files`	List all tracked files with pipeline status
`file_status`	Detailed status for a single file across all stages
`get_logs`	Query session logs (oldest first, INFO excluded)

Full documentation: docs/mcp.md

Remote / HTTP Mode

Start the server on a network-accessible endpoint:

# SSE transport (legacy)
darwin mcp --sse --host 0.0.0.0 --port 8765

# Streamable HTTP transport (recommended for production)
darwin mcp --http --host 0.0.0.0 --port 8765

Configure your MCP client with the URL:

{
  "mcpServers": {
    "darwin": {
      "url": "http://your-host:8765/mcp"  // or /sse for SSE mode
    }
  }
}

Environment Variables

Variable	Required	Description
`OPENAI_API_KEY`	No*	OpenAI provider key
`ANTHROPIC_API_KEY`	No*	Anthropic provider key
`GEMINI_API_KEY`	No*	Google Gemini provider key
`MISTRAL_API_KEY`	No*	Mistral AI provider key
`GROQ_API_KEY`	No*	Groq provider key
`COHERE_API_KEY`	No*	Cohere provider key
`TOGETHER_API_KEY`	No*	Together AI provider key
`OPENROUTER_API_KEY`	No*	OpenRouter provider key
`DEEPSEEK_API_KEY`	No*	DeepSeek provider key
`DARWIN_BASE_DIR`	No	Override the base data directory
`NO_COLOR`	No	Set to any value to disable ANSI color output

* At least one LLM provider key is required for answer generation. Search/indexing works without any.

Setup Details

Command	What it does
`darwin-admin setup interactive`	Guided setup — detect hardware, choose models
`darwin-admin setup --preset required`	Download embedding model only (fastest)
`darwin-admin setup --preset recommended`	Embedding + reranker + OCR models
`darwin-admin setup logging`	Reconfigure logging only
`darwin-admin setup validate`	Validate current setup

See docs/setup.md for the full walkthrough including Docker, from-source install, and API key configuration.

CLI Reference

darwin — User CLI

Command	Description
`darwin mcp`	Start MCP server (stdio, `--sse` or `--http` for network)
`darwin config [client]`	Generate MCP client config

darwin-admin — Power-user CLI

Command	Description
`darwin-admin setup`	Setup models, logging, and configuration
`darwin-admin status`	System status overview
`darwin-admin models`	Model registry: list, install, switch, keys
`darwin-admin store`	Data store: status, files, audit, health, repair
`darwin-admin pipeline`	Ingestion pipeline: run, ingest, index, purge
`darwin-admin search`	Interactive search
`darwin-admin logs`	Structured log viewer and management
`darwin-admin system`	System information
`darwin-admin uninstall`	Remove Darwin data and configuration

See docs/admin.md for the full command reference.

Python API

For embedding darwin-rag as a library in your own app:

from core import Darwin

d = Darwin()
d.ingest("./papers", recursive=True)
results = d.search("what is this paper about")
records = d.search_records(filters={"status": "active"})

Full reference: docs/api.md

Documentation

Doc	What
setup.md	Full setup walkthrough
mcp.md	MCP server, tools, resources, transports
admin.md	Admin CLI reference
architecture.md	For developers and contributors
pipeline.md	Ingestion & indexing
retrieval.md	Search engine
storage.md	DarwinStore
models.md	Model registry & inference
logger.md	Structured logging
orchestrators.md	High-level business logic
api.md	Python API (Darwin class)

Contributing

Found a bug? Want to add something? You're welcome here.

Issues — open one at github.com/BrightDotDev/DARWIN/issues
Code — fork, branch, PR. Keep it minimal.
AI-generated code is fine — but you own what you ship. Test it before submitting.

Read CONTRIBUTING.md for the full guidelines.

License

MIT with Attribution — see LICENSE.

Core architecture and implementation by BrightDotDev.

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityActive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

DocsMint
io.github.HiAi-gg
Self-hosted AI-native knowledge workspace with hybrid search, GraphRAG, and MCP.
Documentation Access RAG Systems Knowledge & Memory
171
qsearch A
io.github.theYahia
Multi-engine search for AI agents. Trust scoring, local corpus, MCP-native. Self-hostable, BYOK.
Search RAG Systems
22
ragie
com.mcparmory
Ingest, manage, and retrieve documents for RAG-powered AI applications
RAG Systems Databases Knowledge & Memory
2
Frenchie A
io.github.Lab94
OCR, transcription, file extraction, and image generation for AI agents via MCP.
AI & Machine Learning Image & Video Processing Speech Processing
72

Related MCP Servers

ragi
RAG Systems Search
SusuTawar
A
license
A
quality
D
maintenance
Local-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.
Updated a month ago (2026-08-13 16:07 UTC)
3
16
MIT
Corpus-KB
RAG Systems Search Knowledge & Memory
moliver28
A
license
B
quality
A
maintenance
Local end-to-end RAG system for agentic code editors, exposing retrieval-augmented generation via MCP to any compatible client.
Updated 2 months ago (2026-07-19 16:56 UTC)
33
1
MIT
rag-retriever-mcp
RAG Systems Search
code-lawyer
F
license
A
quality
B
maintenance
A local-first document retrieval engine that mounts as an MCP tool for agents to index files, search for relevant passages, and let the agent's own LLM answer.
Updated 3 months ago (2026-06-23 01:10 UTC)
4
-
corpus-rag
RAG Systems Knowledge & Memory
monahand1023
A
license
Not graded
quality
A
maintenance
MCP server for local RAG over personal notes, PDFs, and documents, enabling plain-English querying and hybrid search with multi-hop context expansion.
Updated 2 days ago (2026-09-09 01:54 UTC)
MIT