Arkiv 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

Variable	Description	Required
ARKIV_NODE_URL	Arkiv node RPC URL	No (defaults to Kaolin testnet)

Command Line Options

Option	Description	Default
--node-url <url>	Arkiv node RPC URL	Kaolin testnet
--help, -h	Show help	-

MCP Tool

query_entities

Query entities from an Arkiv database chain.

Parameters

Parameter	Type	Description	Default
filter	string	Filter expression (see syntax below)	$all
limit	number	Maximum number of entities to return (max 200)	-
cursor	string	Pagination cursor from a previous response	-
withAttributes	boolean	Include attributes in results	true
withMetadata	boolean	Include metadata (owner, creator, expiry) in results	true
withPayload	boolean	Include payload in results (base64 encoded)	true
validAtBlock	number	Query state at a specific block number	-

Filter Syntax

The filter parameter uses the arkiv_query expression language:

Operator	Description	Example
=	Equality	status = "active"
!=	Not equal	status != "deleted"
>, >=, <, <=	Numeric range	score > 100
&&	Logical AND	type = "post" && score > 50
||	Logical OR	status = "active" || status = "pending"
!	Negation	!(status = "deleted")
~	Glob match	name ~ "test*"
!~	Negated glob	name !~ "draft*"

Synthetic attributes (prefixed with $):

Attribute	Description
$all	Match all entities
$owner	Current owner address
$creator	Original creator address (immutable)
$key	Entity key

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