# openviking-mcp

OpenViking: Context Database for AI Agents — semantic search, memory management, resource ingestion, and session management over MCP.

Source: [`volcengine/OpenViking`](https://github.com/volcengine/OpenViking)

OpenViking has a **built-in HTTP MCP endpoint** at `/mcp` on port 1933 — no mcp-proxy needed.

## Prerequisites

A valid `ov.conf` configuration file is required. Generate one:

```bash
docker run --rm -it \
  -v ~/.openviking:/app/.openviking \
  forgejo.corentic.eu/corentic/mcp-fleet-openviking:latest \
  openviking-server init
```

Validate setup:
```bash
docker run --rm -it \
  -v ~/.openviking:/app/.openviking \
  forgejo.corentic.eu/corentic/mcp-fleet-openviking:latest \
  openviking-server doctor
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `OPENVIKING_CONFIG_FILE` | No | Path to ov.conf inside container (default: `/app/.openviking/ov.conf`) |
| `OPENVIKING_CONF_CONTENT` | No | Inline config content (alternative to volume mount) |
| `OPENVIKING_SERVER_HOST` | No | Server bind address (default: `0.0.0.0`) |
| `OPENVIKING_PUBLIC_BASE_URL` | No | Public URL for file upload signed URLs (needed behind reverse proxy) |
| `OPENVIKING_WITH_BOT` | No | Set to `0` to disable VikingBot |

## Usage

```bash
docker run -d \
  --name openviking-mcp \
  -p 1933:1933 \
  -v ~/.openviking:/app/.openviking \
  --restart unless-stopped \
  forgejo.corentic.eu/corentic/mcp-fleet-openviking:latest
```

MCP endpoint: `http://host:1933/mcp`

## Client Configuration

Connect from any MCP client:

```json
{
  "mcpServers": {
    "openviking": {
      "url": "http://host:1933/mcp"
    }
  }
}
```

Add `"headers": {"Authorization": "Bearer your-api-key"}` if auth is configured.

## Tools

| Tool | Description |
|------|-------------|
| `search` | Semantic search across memories, resources, and skills |
| `read` | Read one or more `viking://` URIs |
| `list` | List entries under a `viking://` directory |
| `store` | Store messages into long-term memory |
| `add_resource` | Add a local file or URL as a resource |
| `grep` | Regex content search across `viking://` files |
| `glob` | Find files matching a glob pattern |
| `forget` | Delete a `viking://` URI |
| `code_outline` | Show a file's symbol structure |
| `code_search` | Search symbol names across a directory |
| `code_expand` | Return full source of a named symbol |
| `health` | Check service health |
| `list_watches` | List auto-refresh subscriptions |
| `cancel_watch` | Cancel a watch task |