Arkiv MCP Server

A Model Context Protocol (MCP) server that exposes Arkiv database chain querying capabilities to AI agents and applications.

Quick Start

1. Build

cd arkiv-mcp
npm install
npm run build

2. Add to Claude Code

Run this from the arkiv-mcp directory:

claude mcp add arkiv -- node $(pwd)/dist/index.js

Or add it manually to ~/.claude/settings.json:

{
  "mcpServers": {
    "arkiv": {
      "command": "node",
      "args": ["/absolute/path/to/arkiv-mcp/dist/index.js"]
    }
  }
}

For Claude Desktop, add the same block to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

3. Query the Kaolin testnet

Once connected, the query_entities tool is available. Example prompts:

• "Query all entities on Arkiv"
• "Find all Arkiv entities where type = "post" and score > 10"
• "Show me entities owned by 0x1234... on the Arkiv testnet"
• "Get the first 5 entities matching status = "active", then paginate"

Features

• Query entities from Arkiv database chains using a SQL-like filter expression
• Full arkiv_query syntax: comparisons, logical operators, glob matching, synthetic attributes
• Pagination support with cursor
• Configurable return fields (attributes, metadata, payload)
• Defaults to Kaolin testnet

Installation

cd arkiv-mcp
npm install
npm run build

# Or use tsx for development
npm run dev

Usage

Start the server

# Using default Kaolin testnet
npm start

# With custom node URL
npm start -- --node-url https://your-arkiv-node.rpc

# Or with tsx for development
npm run dev -- --node-url https://your-arkiv-node.rpc

Environment Variables

Command Line Options

MCP Tool

query_entities

Query entities from an Arkiv database chain.

Parameters

Filter Syntax

The filter parameter uses the arkiv_query expression language:

Synthetic attributes (prefixed with $):

Filter Examples

# All entities
$all

# By entity key
$key = "0xabc123..."

# By owner or creator
$owner = "0x1234567890abcdef..."
$creator = "0x1234567890abcdef..."

# Attribute equality
status = "active"
type = "post"

# Numeric range
score > 100
price >= 50 && price <= 200

# Compound
project = "myapp" && type = "post" && score > 10

# Glob matching
name ~ "draft*"
!(status = "deleted")

Response Format

{
  "entities": [
    {
      "key": "0x...",
      "owner": "0x...",
      "creator": "0x...",
      "createdAtBlock": "12345",
      "lastModifiedAtBlock": "12350",
      "expiresAtBlock": "99999",
      "contentType": "application/json",
      "payload": "<base64-encoded bytes>",
      "attributes": [
        { "key": "type", "value": "post" },
        { "key": "score", "value": 42 }
      ]
    }
  ],
  "cursor": "0x2a",
  "blockNumber": "12350",
  "count": 1
}

Paginate by passing the returned cursor back as the cursor parameter in the next call. When cursor is absent, there are no more results.

Development

The server uses:

• @arkiv-network/sdk — Arkiv TypeScript SDK
• @modelcontextprotocol/sdk — MCP Server SDK

Project Structure

arkiv-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── package.json
├── tsconfig.json
└── README.md

License

MIT