openviking-mcp

OpenViking MCP Server

HTTP MCP server that exposes OpenViking RAG capabilities as tools for Claude and other MCP clients.

What It Provides

Tool	Purpose
query	Full RAG pipeline — semantic search + LLM answer generation
search	Semantic search only, returns matching documents with scores
add_resource	Ingest files, directories, or URLs into the database

Prerequisites

• Python 3.13+
• uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
• OpenAI API key (for LLM and embeddings)

Setup Steps

Step 1: Get the Code

Clone the OpenViking repository:

git clone https://github.com/ZaynJarvis/openviking.git
# Or your fork/organization's repo
cd openviking/examples/mcp-query

Step 2: Install Dependencies

uv sync

Step 3: Configure API Keys (Human Input Required)

Copy the example config:

cp ov.conf.example ov.conf

You must edit ov.conf and add your API tokens. The critical fields:

Field	Purpose	Example
vlm.token	LLM for generating answers	sk-... (OpenAI)
embedding.token	Embeddings for semantic search	sk-... (OpenAI)

Wait for user to confirm: Ask the user to paste their ov.conf (with tokens redacted if sharing logs) or confirm they've set it up before proceeding.

Example minimal config:

{
  "vlm": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "token": "YOUR_OPENAI_API_KEY"
  },
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "token": "YOUR_OPENAI_API_KEY"
  }
}

Step 4: Start the Server

uv run server.py

Server runs at http://127.0.0.1:8000/mcp by default.

Step 5: Connect to Claude

Claude CLI:

claude mcp add --transport http openviking http://localhost:8000/mcp

Claude Desktop: Add to ~/.mcp.json:

{
  "mcpServers": {
    "openviking": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Server Options

uv run server.py [OPTIONS]

  --config PATH       Config file path (default: ./ov.conf)
  --data PATH         Data directory path (default: ./data)
  --host HOST         Bind address (default: 127.0.0.1)
  --port PORT         Listen port (default: 8000)
  --transport TYPE    streamable-http | stdio (default: streamable-http)

Environment variables: OV_CONFIG, OV_DATA, OV_PORT, OV_DEBUG

Usage Examples

Once connected, Claude can use these tools:

Query with RAG:

"Search my documents for information about Q3 revenue and summarize the findings"

Semantic search only:

"Find documents related to machine learning architecture"

Add documents:

"Index the PDF at ~/documents/report.pdf"
"Add https://example.com/article to my knowledge base"

Troubleshooting

Issue	Solution
Port in use	Change with --port 9000
Config not found	Ensure ov.conf exists or set OV_CONFIG path
Dependencies missing	Run uv sync in the mcp-query directory
Authentication errors	Check your API tokens in ov.conf

Resources

• OpenViking repo: code/openviking/ or https://github.com/ZaynJarvis/openviking