sage-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
sage-mcp
Hybrid semantic search (dense vector + BM25) over local knowledge bases and codebases.
Stack: LlamaIndex · Qdrant (local embedded) · OpenAI or LiteLLM embeddings · FastMCP
Setup
# Include MCP and LiteLLM features
uv tool install 'sage-mcp[mcp,litellm]'uv will download Python 3.11 automatically if it's not already installed.
Related MCP server: RecallForge
Index
# Index all configured KBs
sage index
# Index one KB only
sage index --kb homelab
# Force full re-index (ignore cache)
sage index --forceStatus
# Diff KB files vs cache without embedding
sage status
# Single KB
sage status --kb homelabSearch
# Hybrid search across all KBs
sage search "pihole DNS configuration"
# Limit to one KB
sage search "pihole" --kb homelab
# Filter by frontmatter fields
sage search "storage" --filter type=lxc --filter status=running
# More results
sage search "networking" --top-k 20
# Dense-only (no BM25)
sage search "pihole" --no-hybrid
# JSON output (for scripting / agent use)
sage search "pihole" --json
# Markdown output with full file paths (default template: blockquote)
sage search "pihole" --markdown
# Markdown table layout
sage search "pihole" --markdown --template table
# Custom Jinja2 template
sage search "pihole" --markdown --template ~/my-template.md.j2Markdown templates
The --markdown flag renders results via a Jinja2 template.
Two built-in templates are included:
Name | Description |
| Each chunk indented as a blockquote under a |
| Compact markdown table with score, KB, full file path, and truncated excerpt |
To write a custom template, copy a built-in from sage_mcp/templates/ and pass the file path via --template. The following variables are available:
Variable | Type | Description |
|
| The search query |
|
| Each entry has |
|
| Number of duplicate chunks filtered out |
Each result's text_safe is the chunk text with newlines collapsed to spaces and pipe characters escaped — safe for use inside a Markdown table cell. Use text for blockquote or fenced-code rendering where the original formatting should be preserved.
List KBs
sage list-kbsMCP (AI agent access)
Add to your MCP client config (use absolute paths):
{
"mcpServers": {
"sage-mcp": {
"command": "/path/to/sage-mcp/.venv/bin/sage-mcp",
"args": ["--config", "/path/to/sage-mcp/config.yaml"]
}
}
}The --config flag is optional; without it the server looks for config.yaml in its working directory.
Tools exposed:
search_kb(query, kb?, top_k?, filter_type?, filter_status?)— returns{results: [...], duplicates_removed: N}list_knowledge_bases()— list configured KBs
Config
Edit config.yaml to add KBs or switch the embedding backend. Use config-example.yaml as a template.
Switching to Ollama (once nomic-embed-text is running with GPU acceleration):
embedding:
provider: ollama
model: nomic-embed-text
base_url: http://<ollama-ip>:11434Then sage index --force to re-embed everything.
Incremental updates
The indexer tracks a content hash per file in pipeline_cache/<kb-name>/hashes.json.
Re-running sage index only re-embeds files that have changed. Safe to run on a cron or inotify watch.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
Search your knowledge bases from any AI assistant using hybrid RAG.
Related MCP Servers
- FlicenseAqualityDmaintenanceProvides semantic vector search over local codebases via MCP, enabling hybrid search (dense + sparse + RRF) for any MCP client like GitHub Copilot or Claude Desktop.58-
- AlicenseNot gradedqualityDmaintenanceLocal-first MCP server enabling cross-modal search across text, images, documents, video, and audio transcripts. Provides 26 tools for ingesting, searching, and navigating local file systems with a 3-stage pipeline including reranking.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to search local repositories through hybrid keyword and embedding retrieval, read matched chunks, and list indexed repos via MCP, without API keys or cloud services.MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP hosts to query locally indexed notes, docs, chat logs, and other files via hybrid vector/BM25 retrieval with section-level citations. Exposes tools, resources, and prompts for searching and asking over the indexed content.-