Celestia Agent Kit

All-in-one MCP toolkit for the Celestia blockchain, in TypeScript.

Wallet operations · local-only signing · transfers · staking (delegate / undelegate / redelegate / claim) · IBC transfers · full chain & data-layer exploration (blocks, txs, blobs, namespaces, rollups, validators, governance) — from Claude Code, Cursor, Codex, or directly via the Vercel AI SDK.

Built for humans. Perfect for AI.

Why Celestia Agent Kit

Your mnemonic never leaves your machine. MCP only prepares unsigned transactions — signing happens locally with CosmJS, and the key is never sent to the AI model or a remote server.

Two protection levels.

Simple — a guard hook blocks the agent from reading .env.
Secure — encrypted keystore + a signing daemon in a separate, isolated process; the agent only ever receives the signed txBytes.

Two ways to use.

Subscription (free) — connect MCP to Claude Code / Cursor / Codex and use your existing subscription.
AI SDK (developers) — programmatic agents via the Vercel AI SDK with Claude or OpenAI.

Celestia-native. bech32 celestia1... addresses, utia (6 decimals), bank transfers, x/staking delegation (delegate / undelegate / redelegate / claim rewards), IBC, plus the full Celestia data layer: blobs, namespaces, rollups, and modular-DA stats.

⚠️ Mainnet — real funds. The default network is Celestia mainnet (chain-id celestia, native TIA). /send and /stake move real TIA. There is no faucet on mainnet — fund your address from an exchange/bridge, or switch the kit to the Mocha testnet (CELESTIA_NETWORK=mocha) for low-risk demos. Prefer secure mode with manual approval (npm run signer -- --manual) so every signature needs your y/n.

Architecture

┌────────────────────────────┐
│  You (chat or code)        │
├────────────────────────────┤
│  AI Agent                  │
│  (Claude / GPT)            │
│                            │
│  Sees: wallet address,     │
│        MCP tool results    │
│  Never sees: mnemonic      │
├──────────┬─────────────────┤
│ sign-tx  │  MCP Server     │
│ (local)  │  (remote)       │
│          │                 │
│ Signs tx │  prepare_*      │
│ offline  │  broadcast      │
│ (CosmJS) │  query chain    │
│ Key in   │  staking        │
│ .env or  │  blobs / DA     │
│ keystore │  explorer       │
└──────────┴─────────────────┘

Key principle: the mnemonic NEVER leaves your machine. MCP prepares the unsigned tx → you sign locally → the signed txBytes is broadcast back through MCP.

ℹ️ Celestia's celestia_prepare_* tools return a flat unsigned-tx envelope that already carries the full sign context — chain id, account number, sequence, and fee. Signing is therefore fully offline: even in secure mode the daemon needs no network access.

Quick Start — Claude Code (subscription)

# Clone
git clone https://github.com/stakeme-team/celestia-agent-kit
cd celestia-agent-kit

# Install (in Docker for supply-chain safety)
docker run --rm --network host -v "$(pwd):/app" -w /app node:20-alpine npm install

# Create a wallet (24-word mnemonic, celestia1... address)
npx tsx scripts/wallet-manager.ts generate --simple

# Open Claude Code
claude

Claude Code auto-detects .mcp.json and connects to the Celestia MCP server. Then just chat:

"Show my TIA balance, then delegate 0.1 TIA to a validator with low commission"

See also: Cursor setup · Codex setup

Quick Start — AI SDK (programmatic)

git clone https://github.com/stakeme-team/celestia-agent-kit
cd celestia-agent-kit
docker run --rm --network host -v "$(pwd):/app" -w /app node:20-alpine npm install

cp .env.example .env
npx tsx scripts/wallet-manager.ts generate --simple
# Edit .env: add ANTHROPIC_API_KEY or OPENAI_API_KEY

npm run demo:wallet    # show wallet address & TIA balance
npm run demo:send      # send TIA to a recipient
npm run demo:stake     # delegate TIA to a validator

Switch model provider in .env:

AI_PROVIDER=anthropic   # or openai

Skills

Built-in Claude Code / Cursor skills (slash commands):

Skill	What it does
`/wallet`	Show wallet address & native TIA balance
`/send`	Send TIA to a `celestia1...` address
`/stake`	Delegate / undelegate / redelegate TIA, claim rewards, review validators (see Staking)

Security

Simple mode (default)

Mnemonic in .env, protected by a guard hook that blocks the agent from reading it.

npx tsx scripts/wallet-manager.ts generate --simple
npm run security-test
# ✓ cat .env            → BLOCKED
# ✓ grep MNEMONIC .env  → BLOCKED
# ✓ echo $MNEMONIC      → BLOCKED
# ✓ python3 read .env   → BLOCKED
# ... all 27 passed ✓

Secure mode (signing daemon)

Mnemonic encrypted in a keystore (scrypt + AES-256-CTR), decrypted only inside a separate daemon process. The agent physically cannot reach the key.

# Create an encrypted wallet
npx tsx scripts/wallet-manager.ts generate --secure

# Start the daemon (separate terminal)
npx tsx scripts/signer-daemon.ts            # auto-approve
npx tsx scripts/signer-daemon.ts --manual   # ask y/n per transaction

┌───────────────────┐     ┌───────────────────┐
│  Agent            │     │  Signer Daemon     │
│  (no key access)  │────▶│  (mnemonic in mem) │
│                   │unix │                    │
│  Gets: txBytes    │◀────│  Signs tx offline  │
└───────────────────┘sock └───────────────────┘

In --manual mode every signing request prints the tx details (chain, msgs, amount, fee) and waits for your y/n — ideal on mainnet. The sign context comes from the prepare envelope, so the daemon stays network-isolated.

The daemon uses a Unix domain socket — run it on Linux/macOS or via Docker (docker compose up signer); on Windows use simple mode or WSL.

Docker isolation

docker compose run --rm install                  # install deps in a container
docker compose run --rm dev npx tsx examples/02-send-tokens.ts
docker compose up signer                          # signer daemon, NO network access

Staking

Celestia staking is standard Cosmos SDK x/staking + x/distribution; the MCP builds the message for you. Pass validator = the operator address (celestiavaloper1...) from list_celestia_validators and delegator = your wallet. Amounts are in utia (TIA × 10⁶ — parseTia("1.5") → "1500000").

celestia_prepare_delegate (delegator, validator, amount, denom) → MsgDelegate.
celestia_prepare_undelegate (delegator, validator, amount, denom) → MsgUndelegate (unbonding ≈ 21 days).
celestia_prepare_claim_rewards (delegator, validators[]) → MsgWithdrawDelegatorReward.
Redelegate is available in direct mode (MsgBeginRedelegate — see below).
Read: get_celestia_account_delegations, get_celestia_account_redelegations, get_celestia_account_undelegations, list_celestia_validators, get_celestia_validator_by_address, get_celestia_staking_distribution.

⚠️ Mainnet — real funds. /stake spends real TIA; confirm the amount and prefer secure mode (y/n per signature). For a dry run, set CELESTIA_NETWORK=mocha first.

Networks

Switch with CELESTIA_NETWORK in .env (alias testnet → mocha). Every field has a per-network default and is overridable via CELESTIA_*.

Network	chain-id	default RPC	MCP
`mainnet`	`celestia`	`celestia-rpc.polkachu.com`	`api.mammoblocks.io/mcp`
`mocha` (testnet)	`mocha-4`	`celestia-testnet-rpc.polkachu.com`	`api-testnet.mammoblocks.io/mcp`

Direct mode (no MCP)

src/direct.ts talks straight to a public Tendermint RPC with CosmJS — query balance, prepare against the node, sign offline, broadcast. Same flat envelope + offline signer as the MCP path, so it's a drop-in for testnet e2e or self-custody without the MCP write tools:

npm run direct -- balance
npm run direct -- send <celestia1_to> <amountTIA>
npm run direct -- delegate <celestiavaloper> <amountTIA>
npm run direct -- undelegate <celestiavaloper> <amountTIA>
npm run direct -- redelegate <src_valoper> <dst_valoper> <amountTIA>
npm run direct -- claim <celestiavaloper> [<celestiavaloper> ...]

MCP Tools

The Celestia MCP server at https://api.mammoblocks.io/mcp exposes read tools over the explorer API plus the local-signing write flow below (88 tools total):

Category	Tools
Transactions (write)	`celestia_prepare_send`, `celestia_prepare_ibc_transfer`, `celestia_simulate_tx`, `celestia_broadcast_signed_tx`
Staking (write)	`celestia_prepare_delegate`, `celestia_prepare_undelegate`, `celestia_prepare_claim_rewards`
Wallet / signing (read)	`celestia_get_account`, `celestia_get_balance`, `generate_disposable_celestia_wallet`
Accounts	`get_celestia_account_by_address`, `get_celestia_account_transactions`, `get_celestia_account_votes`, `get_celestia_account_delegations`, `get_celestia_account_redelegations`, `get_celestia_account_undelegations`, `get_celestia_account_tokens`, `get_celestia_account_vesting`, `get_celestia_associated_address`, `get_celestia_top_accounts`, `get_celestia_top_accounts_statistics`
Blocks	`list_celestia_blocks`, `get_celestia_block_by_height`, `get_celestia_block_stats`, `get_celestia_block_events`, `get_celestia_block_blobs`, `get_celestia_block_messages`, `get_celestia_biggest_blocks`
Transactions (read)	`list_celestia_transactions`, `get_celestia_transaction_by_hash`, `get_celestia_transaction_statistics`, `get_celestia_transactions_by_block`, `get_celestia_gas_tracker`, `get_celestia_message_types`, `get_celestia_transactions_history`
Validators	`list_celestia_validators`, `get_celestia_validators_statistics`, `get_celestia_validators_count`, `get_celestia_validator_by_address`, `get_celestia_validator_delegators`, `get_celestia_validator_signing_info`, `get_celestia_validator_power_events`, `get_celestia_validator_blocks`, `get_celestia_validator_signals`, `list_celestia_validator_signals`, `get_celestia_validator_jails`, `get_celestia_validator_price_feeder_uptime`
Governance	`list_celestia_proposals`, `get_celestia_active_proposals`, `get_celestia_proposal_by_id`, `get_celestia_proposal_tally`, `get_celestia_proposal_votes`, `get_celestia_proposal_validator_votes`
IBC	`get_celestia_ibc_statistics`, `list_celestia_relayers`, `get_celestia_relayer_channels`, `get_celestia_ibc_channel`, `get_celestia_ibc_channel_transactions`
Transfers	`list_celestia_native_transfers`, `list_celestia_ibc_transfers`, `list_celestia_cw20_transfers`, `list_celestia_cw721_transfers`
Blobs / Data Availability	`list_celestia_blobs`, `get_celestia_blob_by_commitment`, `get_celestia_blob_decoded_data`, `get_celestia_top_blobs_by_size`, `get_celestia_top_namespaces`
Namespaces	`list_celestia_namespaces`, `get_celestia_namespace`, `get_celestia_namespace_blobs`
Rollups	`list_celestia_rollups`, `get_celestia_rollups_count`, `get_celestia_rollups_categories`, `get_celestia_rollup`, `get_celestia_rollup_stats`, `get_celestia_rollup_namespaces`, `get_celestia_rollup_blobs`, `get_celestia_rollup_distribution`
Labels	`get_celestia_address_label`, `get_celestia_address_labels_batch`
Chain / stats / search	`get_celestia_chain_network`, `get_celestia_chain_tokenomics`, `get_celestia_indexer_info`, `get_celestia_head`, `get_celestia_tps`, `get_celestia_changes_24h`, `get_celestia_staking_distribution`, `celestia_search`

No faucet on mainnet — for testnet TIA use the Mocha faucet with generate_disposable_celestia_wallet or your own address.

Project Structure

celestia-agent-kit/
├── CLAUDE.md                    # Agent instructions for Celestia
├── .mcp.json                    # Claude Code MCP config
├── .cursor/mcp.json             # Cursor MCP config
├── .codex/config.toml           # Codex MCP config (via mcp-remote)
│
├── .claude/
│   ├── settings.json            # Guard hook config
│   └── skills/                  # /wallet · /send · /stake
│
├── scripts/
│   ├── wallet-manager.ts        # Create / import wallet (mnemonic)
│   ├── sign-tx.ts               # Sign tx (stdin → stdout base64 txBytes)
│   ├── signer-daemon.ts         # Signing daemon (secure mode)
│   ├── direct.ts                # Direct-node CLI (balance/send/stake/…)
│   ├── keystore-utils.ts        # scrypt + AES-256-CTR mnemonic keystore
│   ├── guard.sh                 # Block agent from reading keys
│   └── security-test.ts         # Test guard (attack vectors)
│
├── src/                         # AI SDK core library
│   ├── mcp-client.ts            # MCP client factory
│   ├── network.ts               # mainnet / mocha registry
│   ├── cosmos.ts                # parseUnsignedTx, signOffline, msg builders
│   ├── direct.ts                # Direct-node CosmJS (prepare/broadcast)
│   ├── wallet.ts                # Sign dispatch (local | daemon), address
│   ├── signing-bridge.ts        # Auto-sign celestia_prepare_* results
│   ├── result.ts                # Parse MCP tool results
│   ├── agent.ts                 # Agent factory (Claude + OpenAI)
│   └── utils.ts                 # Helpers
│
├── examples/                    # AI SDK demos (wallet · send · stake)
├── docs/                        # Claude Code / Cursor / Codex setup
├── Dockerfile
└── docker-compose.yml

Requirements

Node.js 20+ and npm
Docker — optional, recommended for supply-chain-isolated installs and the network-less signer
Subscription path: Claude Pro/Max, Cursor Pro, or ChatGPT Pro
AI SDK path: an Anthropic or OpenAI API key

Configuration

Env var	Default	Purpose
`CELESTIA_NETWORK`	`mainnet`	`mainnet` or `mocha` (testnet) — sets chain-id / RPC / MCP defaults
`CELESTIA_MCP_URL`	`https://api.mammoblocks.io/mcp`	MCP server (read + write tools)
`CELESTIA_RPC_URL`	per-network	Tendermint RPC used by direct mode
`SIGNER_MODE`	`simple`	`simple` (mnemonic in .env) or `secure` (keystore + daemon)

To target Mocha testnet, set CELESTIA_NETWORK=mocha in .env — it resolves the mocha chain-id, RPC, and MCP (api-testnet.mammoblocks.io/mcp) automatically.

License

MIT

Navigation Menu

Uh oh!

Repository files navigation

Celestia Agent Kit

Why Celestia Agent Kit

Architecture

Quick Start — Claude Code (subscription)

Quick Start — AI SDK (programmatic)

Skills

Security

Simple mode (default)

Secure mode (signing daemon)

Docker isolation

Staking

Networks

Direct mode (no MCP)

MCP Tools

Project Structure

Requirements

Configuration

License

About

Contributors

Languages

Name		Name	Last commit message	Last commit date
.claude		.claude
.codex		.codex
.cursor		.cursor
assets		assets
docs		docs
examples		examples
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Celestia Agent Kit

Why Celestia Agent Kit

Architecture

Quick Start — Claude Code (subscription)

Quick Start — AI SDK (programmatic)

Skills

Security

Simple mode (default)

Secure mode (signing daemon)

Docker isolation

Staking

Networks

Direct mode (no MCP)

MCP Tools

Project Structure

Requirements

Configuration

License

About

Topics

Resources

Stars

Watchers

Forks

Contributors

Languages