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.

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

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.