nearblocks-mcp

A small, remote MCP server that exposes read-only NEAR on-chain wallet data by wrapping the public NearBlocks API. It speaks MCP over Streamable HTTP, so it has a plain https://…/mcp URL — which is exactly what the Agents Market connector model ("Private MCP servers") expects.

Why this exists: NEAR RPC (and RPC-based tools like near-mcp) only expose an account's current state, never its transaction history — history lives in an indexer. NearBlocks is that indexer. This server makes it available to marketplace agents (e.g. wallet-activity-lookup) as a proper HTTPS connector, converting raw chain units to human values and stripping the bulky base64 token icons before anything reaches the model.

Tools

All tools take accountId (e.g. alice.near, a .tg name, or a 64-char implicit address) and an optional network (mainnet default, or testnet). All are read-only.

Tool	What it returns
near_account_summary	Current NEAR balance, staked amount, creation date/age, deletion status.
near_account_transactions	Paginated tx history (hash, ISO time, from/to, success, actions + NEAR deposits).
near_account_activities	Balance-change feed: direction (in/out), counterparty, cause, time.
near_account_ft_transfers	Fungible-token transfers: symbol, human amount, direction, counterparty, time.
near_account_inventory	Current holdings: FT balances + NFT contracts held now.
near_wallet_activity_summary	One-shot report — fetches state + a bounded window of txns/FT transfers/holdings and returns an aggregated, unit-converted summary (balance, in/out counts, NEAR value flow, top counterparties, top methods/contracts, token totals, holdings).

Paginated tools accept perPage (1–50, default 25), cursor (from the previous response), and order (desc/asc). near_wallet_activity_summary accepts txPages (1–4, default 2). Figures in the summary cover the retrieved recent window, not the account's lifetime — the response says so explicitly.

Run locally

Requires Node ≥ 20.

npm install
npm run build
cp .env.example .env      # optionally set NEARBLOCKS_API_KEY; leave MCP_AUTH_TOKEN empty for local dev
npm start                 # POST http://localhost:8080/mcp  ·  GET /health

Environment

Var	Required	Purpose
PORT	no (default 8080)	HTTP listen port (Railway/Fly inject this).
MCP_AUTH_TOKEN	in production	Bearer token callers must send: Authorization: Bearer <token>. Empty = unauthenticated (dev only; logs a warning).
NEARBLOCKS_API_KEY	no	Raises NearBlocks rate limits. Works keyless at the free-tier limit. Server-side only.
NEAR_DEFAULT_NETWORK	no (default mainnet)	Network used when a tool call omits network.

Deploy

Any host that runs a container and gives you an HTTPS URL works (Railway, Fly, Render, …).

docker build -t nearblocks-mcp .
docker run -p 8080:8080 -e MCP_AUTH_TOKEN=$(openssl rand -hex 32) nearblocks-mcp

Set MCP_AUTH_TOKEN (and optionally NEARBLOCKS_API_KEY) as service secrets. Your MCP URL is https://<your-host>/mcp.

Wire it into the Agents Market

1. Deploy this server and copy its https://<host>/mcp URL and the MCP_AUTH_TOKEN.

2. On the platform, Building → Connectors → add a server:

   • url: https://<host>/mcp
   • auth: static_token, header empty (⇒ Authorization: Bearer), token = your MCP_AUTH_TOKEN

3. In an agent's agent.yaml, tick it under private_mcp_servers:

   private_mcp_servers:
     - name: nearblocks
       url: https://<host>/mcp
       auth: static_token
       description: NearBlocks MCP — read-only NEAR wallet state, history, transfers, holdings.
   

The wallet-activity-lookup agent is the intended first consumer: it can call near_wallet_activity_summary in a single tool round instead of hitting the REST API by hand.

MCP details

• Transport: Streamable HTTP, stateless (a fresh server + transport per request — no session state to lose, ideal for a horizontally-scaled connector).
• Endpoint: POST /mcp. GET/DELETE /mcp return 405 (no server-initiated streams in stateless mode). GET /health and GET / are unauthenticated.

License

MIT — see LICENSE.