Skip to main content
Glama
openviking-mcp
by SophiaData

openviking-mcp

Minimal read-only MCP server that exposes OpenViking knowledge retrieval to any MCP-capable agent (DSH, Claude Code, Codex, Cursor, …).

Why this exists

OpenViking ships an official DSH plugin that adds automatic session capture and context injection. This project deliberately does none of that:

  • Read-only. There is no tool that can add, edit or delete OpenViking content. An agent cannot promote conversation into "knowledge" on its own.

  • No capture. Nothing is written back to the server by this process.

  • No bundled memory lifetime. Session capture, context injection and skill syncing stay opt-in and outside this server.

  • stdio only. Works with every MCP client; no HTTP listener to secure.

Use the official plugin if you want automatic memory. Use this if you want an agent that can look things up and nothing more.

Related MCP server: graphiti-folder

Tools

Tool

Purpose

ov_search

Semantic search. Returns URI, score, level and summary for each hit.

ov_read

Read one document's full text (L2) by viking:// URI.

ov_overview

Browse a directory with its generated abstracts (L0/L1).

All three are annotated read-only and idempotent.

Install

Install straight from this repository — no npm release required, npm clones and packs it for you:

npm install -g github:SophiaData/openviking-mcp

Pin a released version instead of tracking master:

npm install -g github:SophiaData/openviking-mcp#v0.1.0

Upgrade or remove later:

npm install -g github:SophiaData/openviking-mcp   # re-run to upgrade
npm uninstall -g openviking-mcp

Or run from a checkout without installing anything globally:

git clone https://github.com/SophiaData/openviking-mcp.git
node openviking-mcp/src/server.mjs

Configure

Environment only — nothing is read from or written to a config file:

Variable

Default

Meaning

OPENVIKING_URL

http://127.0.0.1:1933

OpenViking server base URL

OPENVIKING_API_KEY

(empty)

Sent as X-API-Key when set; leave empty for loopback dev auth

OPENVIKING_TIMEOUT_MS

30000

Per-request timeout

Client registration

DSH

Add to the profile patch ($DSH_HOME/profiles/<profile>/cordis.patch.yml):

- insert:
    - id: openviking-knowledge
      name: "@deepseek-ai/dsh-mcp-client"
      config:
        serverName: "openviking"
        transport: "stdio"
        command: "node"
        args: [ "E:/dev-day/openviking-mcp/src/server.mjs" ]
        env:
          OPENVIKING_URL: "http://127.0.0.1:1933"
        failOnStartupError: false

Claude Code

claude mcp add openviking --scope user -- node /path/to/openviking-mcp/src/server.mjs

Codex

# ~/.codex/config.toml
[mcp_servers.openviking]
command = "node"
args = ["/path/to/openviking-mcp/src/server.mjs"]
env = { OPENVIKING_URL = "http://127.0.0.1:1933" }

Verify

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"ov_search","arguments":{"query":"partition filter"}}}' \
  | node src/server.mjs

You should see three tool definitions and a search result block. If the server is down, the tool returns an explicit error instead of an empty list.

Limitations

  • Read-only by design; write tools are intentionally absent.

  • Requires a running OpenViking server with imported resources. An empty store returns "No results".

  • ov_read returns at most 20,000 characters; use OpenViking's own pagination for longer documents.

  • Tested against OpenViking 0.5.2.

License

MIT

Available Tools

3 tools
ov_overviewA
Read-onlyIdempotent

Inspect OpenViking directory structure with generated summaries (L0/L1). Use it to survey what knowledge exists before deciding what to search or read.

Inputs: uri, depth.

ov_readA
Read-onlyIdempotent

Read the full text of one OpenViking document by URI (L2 content). Use it after ov_search when a hit looks relevant and you need the complete section.

Inputs: uri (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    The three tools are clearly separated by purpose: ov_overview surveys structure, ov_search finds relevant documents semantically, and ov_read retrieves full text by URI. Their descriptions explicitly describe a progression, leaving little chance of misselection.

    Naming Consistency5/5

    All tools use the same ov_ prefix followed by a concise action-oriented suffix: search, read, overview. The naming is predictable and easy to scan.

    Tool Count5/5

    Three tools are well-scoped for a read-only knowledge-base MCP. Each operation covers a distinct stage of discovery and retrieval without redundant surface area.

    Completeness5/5

    The set covers the full retrieval lifecycle: survey available knowledge, search by meaning, then read full content. No obvious read-side gaps exist, and write operations are not implied by the server's purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes one or more documentation folders (Markdown, MDX, TXT) to AI agents, enabling listing, reading, and searching of documentation files.
      -
    • A
      license
      A
      quality
      D
      maintenance
      A read-only MCP server that lets you search current and historical facts from a time-indexed knowledge graph derived from a folder of Markdown/text documents, with verification against original sources. It exposes tools for status, fact search, history search, and revision lookup while keeping document insertion and modification to the CLI.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for a content-first knowledge base, enabling AI agents to search (full-text, semantic, hybrid) and retrieve Markdown documents, list content, and find related docs.
      9 npm
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      A read-only MCP server that enables AI clients to search a knowledge base and retrieve complete source documents via narrow search and fetch tools.
      2
      -