Ragnar

You run a local MCP server that uses Retrieval-Augmented Generation to help you search and answer questions from your own documents. It indexes documents in common formats, retrieves context in sentence windows, and serves queries through a programmable MCP interface so you can ask about your data without sending it elsewhere.

How to use

Use a client that supports MCP to connect to your local server. You can query your indexed documents, benefiting from sentence-window retrieval for richer context. You may switch embedding models, point to a local or OpenAI-compatible endpoint, and customize which index root to search.

Run the local SSE server to expose an HTTP endpoint at http://localhost:8001/ragnar where your client can send queries.

python server/sse.py

How to install

Before you begin, ensure you have Python 3.10 or newer and the UV package manager installed on your system.

Install dependencies and set up the project for local use.

# Step 1: Install the project in editable mode via UV
uv pip install -e .

# Step 2: Install the CLI tool locally (stdio mode) if you want to run as a tool
uv tool install .

To index documents for retrieval, run the indexer with your documents folder and an index directory.

python -m indexer.index /path/to/documents /path/to/index

# To customize embedding model and chunk size during indexing
python -m indexer.index /path/to/documents /path/to/index --chunk-size=512 --embed-model BAAI/bge-small-en-v1.5

# If using an OpenAI-compatible embedding endpoint (provide API key via environment)
python -m indexer.index /path/to/documents /path/to/index --embed-endpoint https://api.openai.com/v1 --embed-model text-embedding-3-small --tokenizer-model o200k_base

Additional configuration and runtime notes

Configuration values can be provided via environment variables or a .env file. You typically set the embedding endpoint, model, index root, and a description for the MCP so it can be discovered by clients.

Common environment variables include EMBED_ENDPOINT, EMBED_MODEL, INDEX_ROOT, MCP_DESCRIPTION, and OPENAI_API_KEY for OpenAI-based embeddings. Ensure INDEX_ROOT points to the root directory used by the retriever.

Claude Desktop integration notes

To integrate with Claude Desktop, place a configuration entry under mcpServers that starts the MCP runner with the proper environment settings. The following example shows how to run the local server in a way Claude can query it.

{
  "mcpServers": {
    "mcp-ragnar": {
      "command": "uvx",
      "args": [
        "mcp-ragnar"
      ],
      "env": {
        "OPENAI_API_KEY": "",
        "EMBED_ENDPOINT": "https://api.openai.com/v1",
        "EMBED_MODEL": "text-embedding-3-small",
        "MCP_DESCRIPTION": "My local Rust documentation",
        "INDEX_ROOT": "/tmp/index"
      }
    }
  }
}

Available tools

index_documents

Index documents from the specified path into the local index, supporting multiple formats (txt, md, pdf, doc, docx) and preparing them for retrieval.

query_mcp

Send a query to the local MCP server and receive a context-rich answer based on the indexed documents.

configure_embedding

Switch between local Hugging Face embeddings and remote OpenAI embeddings by setting EMBED_ENDPOINT and EMBED_MODEL.