AlgoMap MCP Server

A Model Context Protocol server that gives AI agents (Claude Desktop, Claude Code, Cursor, etc.) read access to Algorand wallet intelligence from AlgoMap.

Every tool proxies a request to the AlgoMap NestJS API and returns the JSON payload as the tool result.

Prerequisites

• Node.js 18+ (uses the global fetch)
• A running AlgoMap API — by default http://localhost:3005

Install from npm

npm install -g @algomap/mcp
# then in your MCP client config:
# { "command": "algomap-mcp", "env": { "ALGOMAP_API_BASE": "https://algomapp.com" } }

Or run without installing via npx -y @algomap/mcp.

Install & build

From the monorepo root (development):

npm install          # installs the apps/mcp workspace
npm run build --workspace=apps/mcp

Output goes to apps/mcp/dist/.

Run

node apps/mcp/dist/index.js

The server speaks MCP over stdio, so it is designed to be spawned by an MCP client rather than run in a terminal by itself. Point your client's MCP config at the built entry point:

{
  "mcpServers": {
    "algomap": {
      "command": "node",
      "args": ["/absolute/path/to/algomap/apps/mcp/dist/index.js"],
      "env": {
        "ALGOMAP_API_BASE": "http://localhost:3005"
      }
    }
  }
}

ALGOMAP_API_BASE is optional and defaults to http://localhost:3005.

Manual smoke test

To confirm the server boots and the tools register correctly, pipe an MCP initialize + tools/list exchange into it:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"0.0.1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | node apps/mcp/dist/index.js

Tools

| Tool | Description | API endpoint | | ------------------------- | ------------------------------------------------------- | -------------------------------------------- | | get_wallet | Wallet summary: tx count, risk score, flags, cluster | GET /api/v1/wallet/:address | | get_wallet_transactions | Recent transactions (optional limit, up to 200) | GET /api/v1/wallet/:address/transactions | | get_wallet_assets | Asset holdings / transfer volume per asset | GET /api/v1/wallet/:address/assets | | get_counterparties | Peer wallets ranked by transfer count/volume | GET /api/v1/wallet/:address/counterparties | | trace_wallet | Transfer graph around a wallet (depth hops) | GET /api/wallet/:address/graph | | find_path | Hop-by-hop path between two wallets (client-side BFS) | GET /api/wallet/:address/graph | | get_transaction | Single transaction by hash | GET /api/v1/transaction/:txid | | get_wallet_statistics | Wallet risk statistics (risk score, pagerank, activity) | GET /api/v1/wallet/:address | | search_wallets | Top wallets by risk score, filtered by address/label | GET /api/analytics/top |

All inputs are validated (JSON Schema via zod): address must be a 58-char base32 Algorand address, txid a 52-char base64 transaction hash, and numeric arguments are range-checked.

Example agent prompts

Show me the risk profile of wallet A2VO...4YFQ.

What are the top 10 counterparties of A2VO...4YFQ?

Find a path between A2VO...4YFQ and K3Q5...9XZC.

What assets does A2VO...4YFQ hold?

Find the transaction 52-char-hash.

Development

npm run dev --workspace=apps/mcp        # tsx watch
npm run typecheck --workspace=apps/mcp
npm run build --workspace=apps/mcp

Notes

• find_path fetches both wallets' local graphs from /api/wallet/:address/graph and runs a client-side BFS over the union, bounded to 5 hops.
• trace_wallet maps depth (1–5) onto the graph fetch size.
• Results are returned as pretty-printed JSON text content.
• The MCP server itself holds no Algorand keys and performs only read-only lookups against the API.