# OpenViking MCP Server

A lightweight [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that connects to a running [OpenViking](https://github.com/volcengine/openviking) server via HTTP, exposing its context database capabilities to Claude Desktop and other MCP clients.

**No native compilation required** -- only depends on `httpx` and `mcp`.

## Prerequisites

- Python 3.10+
- A running OpenViking server (`openviking-server` on port 1933 by default)

## Installation

```bash
pip install ./openviking-mcp
# or with uv
uv pip install ./openviking-mcp
```

## Claude Desktop Setup

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "openviking": {
      "command": "openviking-mcp",
      "args": ["--server-url", "http://localhost:1933"],
      "env": {
        "OPENVIKING_API_KEY": "your-key-here"
      }
    }
  }
}
```

## Claude Code Setup

```bash
claude mcp add openviking -- openviking-mcp --server-url http://localhost:1933
```

Or with HTTP transport:

```bash
openviking-mcp --transport streamable-http --port 2033
claude mcp add --transport http openviking http://127.0.0.1:2033/mcp
```

## Available Tools

| Tool | Description |
|------|-------------|
| `search` | Semantic search across memories, documents, and resources |
| `add_resource` | Ingest a file, directory, or URL for indexing |
| `read_content` | Read the full content of a resource by URI |
| `get_overview` | Get a structured summary of a resource (L1) |
| `get_abstract` | Get a one-line summary of a resource (L0) |
| `list_contents` | Browse directory contents at a Viking URI |
| `add_memory` | Store information for future recall |
| `find_by_pattern` | Find resources by filename glob pattern |
| `grep_content` | Exact text/regex search within resources |
| `get_resource_info` | Get resource metadata (type, size, status) |
| `get_relations` | View links between resources |
| `health_check` | Check OpenViking server connectivity |

## CLI Options

| Flag | Env Var | Default | Description |
|------|---------|---------|-------------|
| `--server-url` | `OPENVIKING_URL` | `http://localhost:1933` | OpenViking server URL |
| `--api-key` | `OPENVIKING_API_KEY` | | API key for authentication |
| `--transport` | | `stdio` | `stdio` or `streamable-http` |
| `--host` | | `127.0.0.1` | Bind host (HTTP transport) |
| `--port` | `OPENVIKING_MCP_PORT` | `2033` | Bind port (HTTP transport) |
| `--timeout` | | `60` | HTTP request timeout (seconds) |
| `--debug` | `OPENVIKING_MCP_DEBUG` | `false` | Enable debug logging |

## License

Apache-2.0