OpenViking MCP Plugin for Grok CLI

Connect Grok CLI / Grok Build to an OpenViking context database.

The plugin ships a stdio → HTTP MCP proxy that:

• Starts as a local MCP server inside Grok
• Forwards JSON-RPC to your OpenViking server’s /mcp endpoint
• Reads credentials from ~/.openviking/ovcli.conf or OPENVIKING_* env vars
  (no API key pasted into ~/.grok/config.toml)

You get the full OpenViking tool surface: health, find, search, recall, remember, list, read, glob, grep, code tools, add_resource, and more.

Requirements

• Grok CLI installed and logged in (grok login)
• Node.js 18+
• A reachable OpenViking server (local or hosted)

Quick install

bash <(curl -fsSL https://raw.githubusercontent.com/shpaw415/openviking-grok-plugin/main/install.sh)

The installer will:

1. Write or update ~/.openviking/ovcli.conf (URL + API key)
2. Run grok plugin install … --trust
3. Enable the plugin

Non-interactive

bash <(curl -fsSL https://raw.githubusercontent.com/shpaw415/openviking-grok-plugin/main/install.sh) \
  --url 'https://your-openviking.example.com' \
  --api-key 'YOUR_KEY' \
  --yes

Local unauthenticated server:

./install.sh --url 'http://127.0.0.1:1933' --api-key '' --yes --local

Install without the script

# 1. Credentials
mkdir -p ~/.openviking
cat > ~/.openviking/ovcli.conf <<'EOF'
{
  "url": "https://your-openviking.example.com",
  "api_key": "YOUR_KEY"
}
EOF
chmod 600 ~/.openviking/ovcli.conf

# 2. Plugin
grok plugin install shpaw415/openviking-grok-plugin --trust
grok plugin enable openviking

Or from a checkout:

git clone https://github.com/shpaw415/openviking-grok-plugin.git
cd openviking-grok-plugin
./install.sh --local --yes

MCP-only (absolute path, no plugin manager)

Useful if you prefer config.toml registration:

./install.sh --local --mcp-only --yes
# → grok mcp add openviking -- node /path/to/servers/mcp-proxy.mjs

Verify

grok mcp doctor openviking
# In a session:
#   /ov          → status report
#   /mcps        → openviking ready

Ask Grok:

Use the openviking MCP: run health, then list viking://resources.

What you get

Component	Path	Purpose
MCP proxy	servers/mcp-proxy.mjs	stdio bridge to OpenViking /mcp
Status	/ov command	Health, identity, toggles
Skill	skills/openviking	When/how to use the tools
Rule	rules/openviking.md	Prefer recall over guessing

Configuration

Priority (highest → lowest):

1. Environment: OPENVIKING_URL / OPENVIKING_BASE_URL, OPENVIKING_API_KEY / OPENVIKING_BEARER_TOKEN, OPENVIKING_ACCOUNT, OPENVIKING_USER
2. ~/.openviking/ovcli.conf (or OPENVIKING_CLI_CONFIG_FILE)
3. ~/.openviking/ov.conf (legacy server config)
4. Default http://127.0.0.1:1933

Example ovcli.conf:

{
  "url": "https://openviking.example.com",
  "api_key": "…",
  "account": "optional-team",
  "user": "optional-user"
}

Optional:

Variable	Effect
OPENVIKING_DEBUG=1	Proxy + plugin debug logs under ~/.openviking/logs/
OPENVIKING_PEER_ID	Stable peer id for multi-workspace isolation
OPENVIKING_WORKSPACE_PEER=0	Disable workspace-derived peer

Do not put the bearer token in [mcp_servers.openviking.headers] if you use this plugin — the proxy already authenticates. If you previously added a raw HTTP MCP entry in config.toml, remove or disable it to avoid two servers with the same tools:

grok mcp remove openviking   # only if it was the old HTTP entry
# reinstall via this plugin afterward

Uninstall

bash <(curl -fsSL https://raw.githubusercontent.com/shpaw415/openviking-grok-plugin/main/install.sh) --uninstall
# or
grok plugin uninstall openviking --confirm

ovcli.conf is kept so other harnesses (Claude Code, Cursor, …) keep working.

Development

git clone https://github.com/shpaw415/openviking-grok-plugin.git
cd openviking-grok-plugin
grok plugin validate .
./install.sh --local --yes

Proxy smoke test (credentials required):

# Initialize handshake over stdio (partial)
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  | node servers/mcp-proxy.mjs

Relationship to upstream OpenViking

The stdio proxy core is adapted from the official OpenViking memory plugins (examples/memory-plugin-shared, examples/claude-code-memory-plugin), licensed Apache-2.0. This repository packages a Grok CLI–first distribution with an installer and Grok plugin manifest (.grok-plugin/plugin.json).

Upstream also ships Claude Code, Codex, Cursor, and other harness plugins. Use those installers for non-Grok agents:

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh)

License

Apache-2.0 — see LICENSE.

Links

• OpenViking
• OpenViking docs
• Grok plugins guide (Plugins / MCP)