oak-mcp

Model Context Protocol server exposing the OAK (OnChain Attack Knowledge) framework as queryable tools for AI coding agents.

Plug it into Claude Desktop, Cursor, Cline, Zed, or any other MCP-aware AI environment, and your agent gains structured access to:

• 14 Tactics × 62 Techniques covering crypto attack patterns (token launches, smart-contract exploits, bridge compromises, custody breaches, NFT attacks, account abstraction, validator attacks, plus the full laundering pipeline)
• 40 Mitigations with class / audience / Technique-mapping
• 40 Software entries (drainer kits, DPRK malware families, ransomware binaries, commodity infostealers, crypto-specific tooling)
• 142 worked incident examples spanning 2011–2025 with attribution-strength labels
• 416 machine-readable relationships across the corpus

Use cases

• During an audit — agent asks "is this contract pattern OAK-T1.001 (Modifiable Tax)?" and gets the full Technique definition with detection signals
• During incident response — agent looks up which Mitigations apply to a freshly-observed attack class
• During detection-engineering — agent enumerates observed indicators for a Technique and emits Forta-/Dune-shaped queries
• During threat-intel — agent cross-references a software family against the Technique surface it has been observed using

Install

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "oak": {
      "command": "npx",
      "args": ["-y", "@onchainattack/oak-mcp"]
    }
  }
}

Cursor

Settings → Features → Model Context Protocol → Add server:

{
  "oak": {
    "command": "npx",
    "args": ["-y", "@onchainattack/oak-mcp"]
  }
}

Cline (VS Code)

Settings → Cline → MCP Servers:

{
  "mcpServers": {
    "oak": {
      "command": "npx",
      "args": ["-y", "@onchainattack/oak-mcp"]
    }
  }
}

Zed

~/.config/zed/settings.json:

{
  "context_servers": {
    "oak": {
      "command": {
        "path": "npx",
        "args": ["-y", "@onchainattack/oak-mcp"]
      }
    }
  }
}

From source (development)

git clone [email protected]:onchainattack/oak-mcp.git
cd oak-mcp
npm install              # runs `prepare` → just tsc, no network
node dist/server.js      # fetches snapshot on first run, caches it

To run against a local OAK clone (skip network entirely):

# from the OAK repo, build a local snapshot:
cd /path/to/oak && npm run site:data

# point oak-mcp at it:
cd /path/to/oak-mcp
OAK_MCP_OFFLINE_DATA=/path/to/oak/tools/embedded.json node dist/server.js

Tools exposed

| Tool | Purpose | |---|---| | oak_search | Full-text search across Tactics / Techniques / Mitigations / Software (ranked) | | oak_get_technique | Full Technique entry by OAK-Tn.NNN | | oak_get_tactic | Full Tactic entry by OAK-Tn | | oak_get_mitigation | Full Mitigation entry by OAK-MNN | | oak_get_software | Full Software entry by OAK-SNN | | oak_find_mitigations_for_technique | All Mitigations mapped to a Technique | | oak_find_software_for_technique | All Software observed using a Technique | | oak_find_relationships | Full relationship neighborhood for any OAK entity | | oak_list_techniques | Enumerate Techniques with optional tactic / chain / maturity filter | | oak_dataset_info | Embedded-snapshot metadata: counts, source, fetch timestamp |

Data freshness

@onchainattack/oak-mcp fetches the OAK content snapshot at runtime from https://onchainattack.org/tools/embedded.json and caches it in your platform cache directory. The cache TTL is 24h by default, so every day you get fresh corpus without re-installing the package.

Cache locations:

| Platform | Path | |---|---| | macOS | ~/Library/Caches/oak-mcp/snapshot.json | | Linux | ${XDG_CACHE_HOME:-~/.cache}/oak-mcp/snapshot.json | | Windows | %LOCALAPPDATA%\oak-mcp\Cache\snapshot.json |

If the network is down and the cache is stale, the server still starts and serves the stale snapshot with a warning on stderr. If there is no cache and the network is down, the server fails to start with a hint to set OAK_MCP_OFFLINE_DATA.

Environment overrides

| Variable | Effect | |---|---| | OAK_MCP_OFFLINE_DATA | Absolute path to a local embedded.json. Skips network and cache. | | OAK_MCP_DATA_URL | Override the fetch URL (default https://onchainattack.org/tools/embedded.json). | | OAK_MCP_CACHE_TTL | Cache TTL in seconds (default 86400 = 24h). | | OAK_MCP_NO_CACHE=1 | Bypass the cache for the first load; force re-fetch. | | OAK_MCP_CACHE_DIR | Override the cache directory entirely. |

Contributing

See CONTRIBUTING.md for development setup, coding conventions, and where different kinds of contributions belong (this repo vs. upstream OAK). Security issues: see SECURITY.md.

License

The MCP server code is MIT — see LICENSE. The bundled OAK content is licensed CC-BY-SA 4.0 by the OAK project — see NOTICE for attribution requirements and DISCLAIMER.md.

Links

• OAK website: https://onchainattack.org
• OAK framework repo: https://github.com/onchainattack/oak
• This repo: https://github.com/onchainattack/oak-mcp
• Changelog: CHANGELOG.md
• Corrections / takedowns: https://onchainattack.org/CORRECTIONS.md