Hekkova MCP Server

The permanent memory layer for AI agents. Connect any MCP-compatible AI (Claude, ChatGPT, Gemini, Cursor, custom agents) and mint moments — photos, videos, audio, text — permanently to the Polygon blockchain with IPFS + Filecoin storage, Lit Protocol encryption, and privacy tiers that let you control who sees what.

---

Quick Start

# 1. Install dependencies
npm install

# 2. Copy and configure environment variables
cp .env.example .env
# Edit .env with your Supabase, Thirdweb, Pinata, and Stripe credentials

# 3. Seed the local test account and API key
npm run seed

# 4. Start the development server
npm run dev
# → Server running at http://localhost:3000/mcp

---

Connect with Claude Desktop

Add this to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hekkova": {
      "type": "url",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer hk_test_local_dev_key_12345678"
      }
    }
  }
}

For production, replace the URL and API key:

{
  "mcpServers": {
    "hekkova": {
      "type": "url",
      "url": "https://mcp.hekkova.com/mcp",
      "headers": {
        "Authorization": "Bearer hk_live_YOUR_API_KEY"
      }
    }
  }
}

Get your API key at hekkova.com/dashboard/keys.

---

Tool Reference

Tool	Description
mint_moment	Mint media (photo, video, audio, text) permanently to Polygon. Encrypts based on phase, pins to IPFS, mints ERC-721 NFT. Returns a Block ID.
mint_from_url	Fetch a public URL (tweet, Instagram post, image, web page) and mint it. Extracts og:title and og:image automatically.
list_moments	Paginated list of all minted moments. Filterable by phase, category, or search query.
get_moment	Full details for a single moment by Block ID: CIDs, transaction hash, phase, tags, and more.
update_phase	Change a moment's privacy phase. Costs 1 credit (text/image) or 2 credits (video). Legacy Plan includes 10 free Phase Shifts/month.
export_moments	Export all moments as JSON or CSV. Returns a 24-hour download URL with all Block IDs and IPFS CIDs.
get_balance	Check remaining mint credits, current plan (free / arc_builder / legacy), and phase shift balance.
get_account	Account identity: Light ID, display name, wallet address, default phase, and legacy plan status.

---

Privacy Phases

Phase	Access	Encryption
new_moon	Owner only	Lit Protocol (owner wallet ACC)
crescent	Close circle (2–10 people)	Lit Protocol (shared access conditions)
gibbous	Extended group (up to 50)	Token-gated via Hekkova ERC-721
full_moon	Fully public	None

---

Moment Categories

Category	Meaning
super_moon	Major life event
blue_moon	Rare moment
super_blue_moon	Once-in-a-lifetime
eclipse	Time-locked — sealed until eclipse_reveal_date
null	Uncategorized

---

Rate Limits

Plan	Requests/min	Mints/min
Sandbox (test keys)	10	1
Standard (any paid pack)	60	10
Legacy Plan	120	20

Rate limit headers are included on every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1710680460

---

Running Tests

# Make sure the server is running in another terminal
npm run dev

# Run the test client
npm run test-client

---

Deployment

Vercel (Serverless)

npm install -g vercel
vercel

Add a vercel.json:

{
  "builds": [{ "src": "src/server.ts", "use": "@vercel/node" }],
  "routes": [{ "src": "/(.*)", "dest": "src/server.ts" }]
}

Set all environment variables in the Vercel dashboard under Project → Settings → Environment Variables.

Railway

... [View full README on GitHub](https://github.com/Hekkova/hekkova-mcp#readme)