Power your agent
Cài đặt từ nhà phát hành. Không phải endpoint của PlugMCP.
Host a copy with our keys and logs.
Chưa có bản phát hành đóng gói nào trong registry. Làm theo README của kho mã.
URL từ xa hay một lệnh trên máy của bạn? Hai cách cài đặt khác nhau thế nào
Chạy trên PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
MởTừ nhà phát hành
Local RAG server for Claude Code, Cursor and other MCP clients: hybrid BM25 + vector search with cross-encoder reranking on by default, 13 MCP tools, 33 file types including code, re-indexing on file changes. One Python process with embedded ChromaDB and FastEmbed ONNX: no Docker, database server or API key; offline after the first model download.
Hybrid search · Cross-encoder reranking · 35 file formats · 100% local · Zero cloud · Enterprise-grade plumbing built-in.
pip install knowledge-rag → restart Claude Code → search_knowledge("your query")
Chart updated daily by GitHub Action
Most RAG frameworks fall into one of three traps: (1) they require you to ship your data to a cloud API, (2) they hand you 300 building blocks and 0 opinionated defaults, or (3) they bundle RAG as a 5% feature of a much bigger platform you didn't ask for.
knowledge-rag is an MCP-native local RAG server for clients such as Claude Code, Cursor, Windsurf, VS Code, Cline, Gemini CLI and Zed. It includes optional bearer authentication, Prometheus metrics, rate limiting, health probes, structured JSON logging and staging-based rebuilds. Configure the transport and access controls for the intended deployment.
Embedding generation, indexing, and retrieval run locally. Model downloads and add_from_url use network access, and configured MCP clients receive retrieved content. Choose the corpus, client permissions, and network exposure to fit your deployment; this project does not certify regulatory compliance.
pip install knowledge-rag → restart your MCP client → done. No Docker mandatory. No Ollama required. No separate embedding server. Everything runs in-process via FastEmbed ONNX. Works offline after the first model download.
7-pillar quality workflow, a 9-cell OS×Python CI matrix (Linux + Windows + macOS × 3.11/3.12/3.13), and nightly chaos, bounded-memory soak and mutation tests. Inspect the checks on the revision being deployed; CI coverage is not a guarantee of zero defects.
No token bills. No SaaS tier. No paid features hidden behind a wall. MIT license, forever. Runs on the laptop you already have — GPU optional, CPU works fine with FastEmbed ONNX.
Compare the features needed for your deployment rather than treating framework checklists as a benchmark. Knowledge-rag combines MCP tools, local embeddings, ChromaDB persistence, BM25, optional FTS5 and optional reranking in one process.
Pick your integration path — knowledge-rag ships the same server through every channel.
pip install knowledge-rag
knowledge-rag init # scaffolds config.yaml + documents/
Drop your PDFs, markdown, code files into documents/. Restart your MCP client. Ask it:
search_knowledge("your query")
That's it. First query loads the ONNX embedding model (~200MB, one-off download). Subsequent queries are cached and hit sub-second latency.
# config.yaml
server:
transport: "sse" # or "streamable-http"
host: "0.0.0.0"
port: 8179
auth:
bearer_token: "your-secret-token"
rate_limit:
enabled: true
requests_per_minute: 60
metrics:
enabled: true
port: 9179
logging:
format: "json" # ELK / Loki / Datadog / CloudWatch ready
knowledge-rag --transport sse
curl http://your-host:8179/health → 200 + JSON payloadhttp://your-host:9179/metricsAuthorization: Bearer your-secret-tokenstdio is ideal when one MCP client owns one knowledge-rag process. If several clients (e.g. Claude, Cursor, LM Studio, or multiple terminal windows) should share one index and one running process, run knowledge-rag once with Streamable HTTP and point each HTTP-capable client at the same endpoint (prompted by #217 and issue #223):
knowledge-rag --transport streamable-http
# MCP endpoint: http://127.0.0.1:8179/mcp
http://127.0.0.1:8179/mcp.127.0.0.1. You must expose your server via a secure, publicly accessible HTTPS endpoint (e.g. Cloudflare Tunnel, ngrok, or reverse proxy) at https://your-public-domain/mcp. Configure the proxy to send an upstream Host accepted by the HTTP app for server.host (for the default loopback configuration, use 127.0.0.1:8179); forwarding the public hostname unchanged can produce 421 Invalid Host header. Keep bearer authentication and HTTPS enabled. Local claude_desktop_config.json uses command/args for local stdio processes and does not support remote HTTP endpoints.Authorization with value Bearer <your-token> matching server.auth.bearer_token in config.yaml (see Anthropic Custom Connectors documentation).When an HTTP transport is selected, knowledge-rag automatically enables its single-instance lock (KNOWLEDGE_RAG_SINGLE_INSTANCE=1) to prevent multiple servers from binding the same data directory or port.
Security note: The default host is
127.0.0.1. If you bind to0.0.0.0or deploy across a network, configureserver.auth.bearer_tokeninconfig.yamland terminate TLS (HTTPS) via a reverse proxy (e.g. Caddy, Nginx) to protect bearer tokens in transit; otherwise the server warns that the HTTP endpoint is unauthenticated.
docker pull ghcr.io/lyonzin/knowledge-rag:latest
docker run -v $(pwd)/documents:/app/documents -p 8179:8179 ghcr.io/lyonzin/knowledge-rag:latest
Full installation guide with all 5 methods, 8 MCP client configurations, and GPU setup: docs/INSTALLATION.md →
Installing knowledge-rag gives your agent 13 MCP tools. It does not tell the agent when to use them. That is what the skills/ folder solves — drop-in behavioural skills for Claude Code, Cursor, Windsurf, Cline, Zed, VS Code Copilot that turn "AI with access to RAG" into "AI that actually uses RAG first".
10 skills, MIT licensed, organized by kind:
Install — pick the shortest path for your machine:
# Option 1 — Via skills.sh (needs Node — one command, zero clone)
npx skills add lyonzin/knowledge-rag
# Option 2 — Via our install.sh (no Node needed; works on Linux/macOS/WSL/Git Bash)
curl -fsSL https://raw.githubusercontent.com/lyonzin/knowledge-rag/master/skills/install.sh | bash
Both restart-Claude-Code and you are done. Option 2 supports --project, --only rag-check-first,rag-cite-sources, --dry-run, --help.
For Cursor, Windsurf, Cline and full manual instructions → skills/README.md · Full catalog with skill chains → skills/CATALOG.md
Once installed, your AI agent gets these 13 tools automatically:
Full API reference with parameter details, return schemas, examples: docs/API.md →
Every RAG framework claims "production-ready." Here is what knowledge-rag ships in the OSS core, verified by regression tests, that competitors either paywall, plugin-ify, or simply don't have.
hmac.compare_digest), RFC 6750 challenge, 401 fenced with WWW-Authenticate headervalidate_path_within guarding 6 CRUD tools (CWE-22, CWE-59)/metrics endpoint — custom histogram buckets tuned for RAG (p95 ≤ 10ms fast-path targets), 7 canonical metrics via @instrument decorator on all 13 toolsGET /health and /healthz returning {status, version, uptime_seconds, cache} in front of the auth middleware (probes always succeed)server.logging.format: "json", one JSON object per record ready for ELK / Loki / Datadog / CloudWatchget_reindex_status() pollingtests/chaos/)KNOWLEDGE_RAG_SOAK_ITERATIONS=50000); this is not a one-hour real-model endurance testinstance_lock + preflight — catches tests that are too weakPreset: cybersecurity.yaml · 8 categories · 200+ routing keywords · 69 query expansions
Ingest MITRE ATT&CK, threat reports, exploit writeups and incident reports. Search from an MCP client with search_knowledge("privilege escalation windows"). Offline operation requires cached models; the chosen client receives retrieved content and determines what happens to it afterwards.
Preset: developer.yaml · 9 categories · 150+ routing keywords · 50+ expansions
Replace Confluence hunting. Ingest architecture docs, ADRs, runbooks, code, API specs. Devs ask their AI agent "how do we authenticate the payment service" and get the exact ADR + implementation file citation.
Preset: research.yaml · 9 categories · 100+ routing keywords · 40+ expansions
Index arXiv papers, lab notebooks, dataset documentation. Semantic search finds papers by intent, not just keywords — cross-encoder reranking surfaces the actually-relevant one instead of five that share a term.
Preset: general.yaml · blank slate, pure semantic search
Deploy via SSE on a single VM. 40+ users authenticated via bearer token, rate-limited, Prometheus-monitored, /health probes wired to your load balancer, JSON logs shipped to Datadog. No cloud calls. Meets LGPD, GDPR, HIPAA data-locality requirements by design.
Verified at scale: production reproduction on a 5 889-doc / 75 016-chunk corpus with concurrent queries during a nuclear rebuild — zero downtime, zero errors (see CHANGELOG v4.8.3).
End-to-end view of how MCP clients, the retrieval pipeline, storage, and enterprise plumbing connect. Every arrow is a real code path — nothing pictured here is aspirational.
flowchart TB
subgraph CLIENTS["MCP Clients (any of these)"]
C1[Claude Code]
C2[Claude Desktop]
C3[Cursor]
C4[Windsurf]
C5[VS Code · Cline · Gemini CLI · Zed]
end
subgraph TRANSPORT["Transport Layer"]
T1[stdio<br/>1 process per client]
T2[SSE / streamable-http<br/>1 server serves N clients]
end
subgraph MIDDLEWARE["ASGI Middleware Chain (HTTP mode)"]
M1[HealthMiddleware<br/>/health · /healthz]
M2[BearerAuthMiddleware<br/>constant-time compare]
M3[Rate Limiter<br/>sliding window]
end
subgraph MCP["13 MCP Tools (frozen contract)"]
MT1[search_knowledge]
MT2[get_document · search_similar]
MT3[add_document · add_from_url · update · remove]
MT4[reindex_documents · get_reindex_status]
MT5[list_documents · list_categories · get_index_stats · evaluate_retrieval]
end
subgraph SEARCH["Retrieval Pipeline"]
R[Query Router<br/>lexical vs semantic]
F[FTS5 Fast-Path<br/>opt-in lexical retrieval]
BM[BM25 Inverted Index<br/>keyword candidates]
SE[Semantic Search<br/>FastEmbed ONNX lazy-loaded]
RRF[Reciprocal Rank Fusion]
CE[Cross-Encoder Rerank<br/>MiniLM-L-6-v2]
QC[Query Cache<br/>LRU + 5-min TTL]
end
subgraph STORAGE["Storage (100% local)"]
CH[ChromaDB<br/>vectors + metadata<br/>WAL mode]
FT[SQLite FTS5<br/>lexical index<br/>WAL + busy-timeout]
MD[index_metadata.json<br/>durable state]
end
subgraph INGEST["Document Ingestion"]
FS[documents/ folder]
WD[Watchdog<br/>10s debounce]
PA[Format parsers<br/>MD · PDF · DOCX · code · IaC · IPYNB]
CK[Chunker<br/>markdown-aware · code-aware]
EM[FastEmbed ONNX<br/>384D bge-small-en-v1.5]
DD[SHA256 Dedup]
SW[Staging Rebuild<br/>rollback on handled publication failure]
end
subgraph OBS["Enterprise Observability (opt-in)"]
PM[Prometheus /metrics<br/>7 canonical + histograms]
LG[Structured JSON logs<br/>ELK · Loki · Datadog · CloudWatch]
HC[Health payload<br/>version · uptime · cache stats]
end
subgraph CFG["Configuration"]
YM[config.yaml<br/>+ 5 domain presets]
end
C1 & C2 & C3 & C4 & C5 -->|MCP protocol| T1
C1 & C2 & C3 & C4 & C5 -.->|remote deploy| T2
T1 --> MCP
T2 --> M1 --> M2 --> M3 --> MCP
MT1 --> QC
QC -->|cache miss| R
R -->|lexical| F
R -->|semantic| SE
R -->|hybrid| BM
F --> CH
F --> FT
BM --> CH
SE --> CH
BM --> RRF
SE --> RRF
RRF --> CE
CE --> QC
MT2 --> CH
MT3 --> INGEST
MT4 --> SW
MT5 --> CH
FS --> WD --> PA
PA --> CK --> EM --> DD --> CH
SW -.->|validated publication| CH
SW -.-> FT
CH -.-> MD
MCP -.->|instrumented| PM
MCP -.->|logs| LG
M1 --> HC
YM -.-> SEARCH
YM -.-> STORAGE
YM -.-> OBS
YM -.-> MIDDLEWARE
classDef client fill:#3776AB,stroke:#1e5a8a,color:#fff
classDef transport fill:#00A67E,stroke:#006e54,color:#fff
classDef middleware fill:#6b46c1,stroke:#4c1d95,color:#fff
classDef storage fill:#4b5563,stroke:#1f2937,color:#fff
classDef obs fill:#dc2626,stroke:#7f1d1d,color:#fff
classDef ingest fill:#f59e0b,stroke:#78350f,color:#fff
class C1,C2,C3,C4,C5 client
class T1,T2 transport
class M1,M2,M3 middleware
class CH,FT,MD storage
class PM,LG,HC obs
class FS,WD,PA,CK,EM,DD,SW ingest
Reading the diagram (top → bottom):
WWW-Authenticate), then rate limiter (sliding window).@rate_limited + @instrument — metrics record calls and the rate limiter enforces RPM+burst when enabled. Disabled features skip that work, while the lightweight wrapper calls remain.search_knowledge checks the query cache first; cache miss routes through the Query Router (regex classifier) to either the FTS5 fast-path (lexical) or the hybrid pipeline (BM25 + semantic + RRF + cross-encoder rerank).index_metadata.json for durable state.documents/; format parsers create chunks, FastEmbed generates embeddings, and source metadata supports incremental updates. Full rebuilds use staging. See the operations guide for publication and recovery limits./metrics, structured JSON logs, /health payload — attaches to the same instrumentation points, no code changes required.config.yaml (with 5 domain presets) controls every subsystem — no environment variable spaghetti, no hardcoded paths.Component ownership, query/ingestion diagrams, memory boundaries and hybrid weights: docs/ARCHITECTURE.md
Parsers use format-specific extraction: Markdown sections, code boundaries, notebook cells without base64 outputs, PDF text and spreadsheet rows. Several extensions share one parser. The runtime fallback list contains 33 formats; the documented template and presets can select a smaller list. Inspect your effective documents.supported_formats. The two MetaTrader extensions are opt-in.
Files with a .pdf extension can also contain an explicit text extraction: the
first line must be [Page N] with a positive page number, followed by nonempty
UTF-8 text. An optional UTF-8 BOM and tab/CR/LF whitespace are accepted. This
recognition is limited to 4 MiB, rejects other C0/C1 controls and DEL, and never
reinterprets a file containing PDF magic in the first 1 KiB as text. Accepted
extractions retain their source path and are marked content_format=extracted_text
and page_count_source=markers; the marker count is not proof of the original
PDF's total page count. Binary PDFs keep the native parser and its error
diagnostics. Invalid or oversized textual lookalikes remain errors.
Enable an opt-in format — add the extension to
documents.supported_formatsin yourconfig.yaml:documents: supported_formats: [".md", ".pdf", ".mq4", ".mqh"]
Full parser reference with per-format notes: docs/CONFIGURATION.md
Claude Code
~/.claude.json
Claude Desktop
claude_desktop_config.json
Cursor
~/.cursor/mcp.json
Windsurf
~/.codeium/windsurf/mcp_config.json
VS Code
Copilot Chat mcp.json
Cline · Gemini CLI · Zed Native MCP
Complete client configuration guide with JSON schemas per client: docs/INSTALLATION.md#use-with-other-mcp-clients →
⚠️ Operating model — read once. In
stdiomode, your MCP client (Claude Desktop, Code, Cursor, etc.) spawns and owns the knowledge-rag server process. Do NOT also run a secondknowledge-ragwriter in a terminal while that stdio client is open — two writer processes against the samedata_dircorrupt the ChromaDB HNSW segment on Windows (see issue #216). For HTTP transports, manually running one server and connecting HTTP clients to it is the supported shared-server workflow; do not mix it with another writer using the samedata_dir. Recommended baseline for stdio clients: add"KNOWLEDGE_RAG_SINGLE_INSTANCE": "1"to theenvblock of your MCP config as a safety net. Full explanation + how to run CLI commands safely: docs/single-instance.md.
⚠️ Do not install under cloud-sync folders. Keep
paths.data_diron a local path. OneDrive (incl.OneDrive - <tenant>), iCloud Drive, Dropbox, Google Drive, Box, pCloud, MEGAsync, Nextcloud/ownCloud and Sync all open file handles on the live index to upload it, racing with ChromaDB's HNSW mmap and SQLite WAL writes and triggering native access violations (0xC0000005on Windows,SIGBUSon *nix). Preflight auto-repair then moves the active index todata/backups/auto-repair-*and you lose the corpus. Since v4.11.0, preflight aborts withEX_CONFIG(78) whendata_dirresolves under one of these providers. Pointdata_dirat a local path (e.g.%LOCALAPPDATA%\knowledge-rag\dataon Windows,~/.local/share/knowledge-rag/dataon Linux/macOS). If you really need to run under cloud sync, setpaths.allow_cloud_sync: trueto acknowledge the risk and continue.
# config.yaml — everything is optional; defaults just work
paths:
documents_dir: "./documents"
data_dir: "./data"
models:
embedding:
profile: "compact" # "compact" | "quality" | "multilingual" | "custom"
gpu: "auto" # "auto" | "true" | "false" | "directml"
device_id: null # DirectML: explicit DXGI adapter index
reranker:
enabled: true # cross-encoder rerank
search:
default_results: 5
max_results: 100
server: # optional — SSE / HTTP mode
transport: "stdio" # or "sse" / "streamable-http"
auth:
bearer_token: "" # set a secret to enable auth
rate_limit:
enabled: false
metrics:
enabled: false
logging:
format: "text" # or "json"
Pre-built presets: cybersecurity.yaml · developer.yaml · research.yaml · general.yaml · multilingual.yaml
Complete configuration reference — every field, every default, tuning guide: docs/CONFIGURATION.md →
knowledge-rag is designed for teams that cannot let their documents leave the perimeter.
OpenSSF Best Practices badge: passing · project ID #13864
Response SLA (best-effort, community project):
/health endpoint + opt-in JSON structured loggingFull history: CHANGELOG.md →
MIT License — LICENSE. Forever. No cloud upsell, no dual-licensing, no restrictive clauses. Fork it, sell derivatives, embed it in commercial products — the license does not care.
Built on the shoulders of amazing open-source projects:
Xenova/ms-marco-MiniLM-L-6-v2 cross-encoderbge-small-en-v1.5 embedding modelCommunity contributors: @Hohlas · @eeshsaxena · Sergey Khokhlov · and everyone who filed issues or PRs.
Built by Ailton Rocha (Lyon.) · Star ⭐ if this saves you time · Report an issue · Contribute
knowledge-rag — the MCP-first local RAG server for Claude Code, Cursor, Windsurf, and every AI agent.
Local RAG server for Claude Code, Cursor and other MCP clients: hybrid BM25 + vector search with cross-encoder reranking on by default, 13 MCP tools, 33 file types including code, re-indexing on file
Tổng quan
Local RAG server for Claude Code, Cursor and other MCP clients: hybrid BM25 + vector search with cross-encoder reranking on by default, 13 MCP tools, 33 file types including code, re-indexing on file changes. One Python process with embedded ChromaDB and FastEmbed ONNX: no Docker, database server or API key; offline after the first model download.
Công cụ
Chưa có danh sách công cụ. Máy chủ từ xa sẽ có danh sách sau lần kiểm tra tình trạng đầu tiên.
Câu hỏi thường gặp
Sao chép cấu hình stdio cho Cursor, Claude Desktop, Claude Code hoặc VS Code trên trang này. Cấu hình dùng bản cài đặt của nhà phát hành, không phải proxy của PlugMCP.
Bản ghi này không liệt kê biến môi trường bắt buộc nào.
Knowledge Rag chạy cục bộ qua stdio.
Kiểm tra lần cuối: 2026-11-15. Local RAG server for Claude Code, Cursor and other MCP clients: hybrid BM25 + vector search with cross-encoder reranking on by default, 13 MCP tools, 33 file types including code, re-indexing on file changes. One Python process with embedded ChromaDB and FastEmbed ONNX: no Docker, database server or API key; offline after the first model download.
