Algorand MCP Server

A comprehensive Model Context Protocol (MCP) server that gives AI agents and LLMs full access to the Algorand blockchain. Built by GoPlausible.

Algorand is a carbon-negative, pure proof-of-stake Layer 1 blockchain with instant finality, low fees, and built-in support for smart contracts (AVM), standard assets (ASAs), and atomic transactions.

What is MCP?

Model Context Protocol is an open standard that lets AI applications connect to external tools and data sources. This server exposes Algorand blockchain operations as MCP tools that any compatible AI client can use — Claude Desktop, Claude Code, Cursor, Windsurf, and others.

Related MCP server: Alchemy MCP Server

Features

• Agent wallet — mnemonics stored in a local SQLite database, used by the MCP server to sign on the agent's behalf (mnemonics never returned in tool responses)

• Wallet accounts with human-readable nicknames

• Account creation, key management, and rekeying

• Transaction building, signing, and submission (payments, assets, applications, key registration)

• Atomic transaction groups

• TEAL compilation and disassembly

• Algod and Indexer API access (accounts, assets, applications and boxes, transactions, node status, search)

• NFDomains (NFD) name service integration

• Pera Wallet asset verification and verified-asset search (mainnet)

• x402 HTTP micropayments — automatic discovery and one-call paid requests using the active wallet (USDC/ALGO), plus Bazaar directory search for paid x402 APIs

• Tinyman AMM integration (pools, swaps, liquidity)

• Haystack Router DEX aggregation (best-price swaps across Tinyman, Pact, Folks)

• Alpha Arcade prediction market trading (browse markets, orderbooks, limit/market orders, positions, claims)

• ARC-90 payment URI and QR code generation (ARC-90 supersedes ARC-26)

• Algorand knowledge base with full developer documentation taxonomy

• Per-tool-call network selection (mainnet, testnet, localnet) and pagination

Requirements

• Node.js v20.19 or later

• npm, pnpm, or yarn

Installation

From npm

npm install -g @goplausible/algorand-mcp

From source

git clone https://github.com/GoPlausible/algorand-mcp.git
cd algorand-mcp
npm install
npm run build

MCP Configuration

The server runs over stdio. There are three ways to invoke it — pick whichever suits your setup:

No environment variables are required for standard use. Network selection and pagination are handled per tool call, and mainnet and testnet node URLs are built in. Optional environment variables set localnet node URLs, a private node token, a Haystack Router API key, an Alpha Arcade API key and base URL (alpha_get_reward_markets needs ALPHA_API_KEY), the default page size and the Bazaar directory URL (see Optional Environment Variables).

OpenClaw

No manual configuration needed — install the @goplausible/openclaw-algorand-plugin npm package and the Algorand MCP server is configured automatically:

npm install -g @goplausible/openclaw-algorand-plugin

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Using npx:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

Using global install:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "algorand-mcp"
    }
  }
}

Using absolute path:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/algorand-mcp/dist/index.js"]
    }
  }
}

Claude Code

Create .mcp.json in your project root (project scope):

{
  "mcpServers": {
    "algorand-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

Or add it from the command line; put --scope user after mcp add to make it available in all your projects:

claude mcp add algorand-mcp -- npx @goplausible/algorand-mcp

Cursor

Add via Settings > MCP Servers, or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

Windsurf

Add via Settings > MCP, or edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

VS Code / GitHub Copilot

Edit .vscode/mcp.json in your workspace root, or open Settings > MCP Servers:

{
  "servers": {
    "algorand-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"]
    }
  }
}

Cline

Add via the MCP Servers panel in the Cline sidebar, or edit ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS):

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "npx",
      "args": ["@goplausible/algorand-mcp"],
      "disabled": false
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.algorand-mcp]
command = "npx"
args = ["@goplausible/algorand-mcp"]

Or add from the command line:

codex mcp add algorand-mcp -- npx @goplausible/algorand-mcp

Open Code

Edit opencode.json in your project root, or ~/.config/opencode/opencode.json for global scope:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "algorand-mcp": {
      "type": "local",
      "command": ["npx", "@goplausible/algorand-mcp"],
      "enabled": true
    }
  }
}

Any MCP-compatible client

The server speaks the standard MCP stdio protocol. For any client not listed above, configure it with:

• Command: npx (or algorand-mcp if globally installed, or node /path/to/dist/index.js)

• Args: ["@goplausible/algorand-mcp"] (for npx)

• Transport: stdio

Network Selection

Every tool except the Pera Wallet tools accepts an optional network parameter: "mainnet", "testnet" (default), or "localnet". Algod and Indexer URLs are built-in for mainnet and testnet via AlgoNode. Localnet needs ALGORAND_LOCALNET_URL (see Optional Environment Variables).

Some integrations are tied to specific networks:

Example tool call:

{ "name": "api_algod_get_account_info", "arguments": { "address": "ABC...", "network": "testnet" } }

If no network is provided, tools default to testnet. Pass "network": "mainnet" for mainnet.

Pagination

Responses from the API tools (api_*) and the Alpha Arcade tools (alpha_*) are automatically paginated. Those tools accept an optional itemsPerPage parameter (default: 10, or the ITEMS_PER_PAGE environment variable). When a response's metadata.hasNextPage is true, call the tool again with the same arguments plus pageToken set to metadata.pageToken to fetch the next page.

Agent Wallet

Architecture

The agent wallet is a local SQLite database that the MCP server controls on the agent's behalf. The server holds the mnemonics and signs transactions for the agent — the agent never sees the mnemonics in any tool response. Each server process loads wallet.db into memory once (sql.js) and rewrites the whole file after every change without re-reading it, so two processes sharing one wallet.db don't see each other's changes and the last one to write wins. Change the wallet from one server process at a time.

Threat model. The wallet.db file is the secret. Anyone with read access to it can recover every mnemonic stored in the wallet. The mitigations are filesystem permissions (0600, owner-only), keeping the data directory off shared/world-readable volumes, and treating the data directory like any other secret store (snapshot it carefully, restrict backups, encrypt the host disk for at-rest protection). For Docker deployments, mount ~/.algorand-mcp as a named volume and restrict access to it like you would any secret material.

How it works

  Agent (LLM)                    MCP Server                          Storage
  ──────────                     ──────────                          ───────
       │                              │                                  │
       │  wallet_add_account          │                                  │
       │  { nickname: "main" }        │                                  │
       │ ──────────────────────────►  │  generate keypair                │
       │                              │  INSERT (address, public_key,    │
       │                              │           nickname, mnemonic) ──►│  wallet.db
       │  ◄─ { address, publicKey,    │                                  │
       │       nickname, index }      │                                  │
       │                              │                                  │
       │  wallet_sign_transaction     │                                  │
       │  { transaction: {...} }      │                                  │
       │ ──────────────────────────►  │  SELECT mnemonic FROM accounts ◄─│
       │                              │   WHERE address=<active>         │
       │                              │  sign in memory                  │
       │  ◄─ { txID, blob }           │  (key discarded after sign)      │
       │                              │                                  │

1. Account creation (wallet_add_account) — Generates a keypair and inserts a row containing the mnemonic into accounts. Returns address, public key, nickname, and index. The mnemonic is never returned.

2. Active account — One account is active at a time. wallet_switch_account changes it by nickname or index. All signing and query tools operate on the active account.

3. Transaction signing (wallet_sign_transaction) — Reads the mnemonic from the DB, signs in memory, returns only the signed blob.

4. Data signing (wallet_sign_data) — Signs arbitrary hex data using raw Ed25519 via the @noble/curves library (no Algorand SDK prefix). Useful for off-chain authentication.

5. Asset opt-in (wallet_optin_asset) — Creates, signs, and submits an opt-in transaction for the active account in one step.

Backward compatibility (silent migration from OS keychain)

Older installs of this MCP stored mnemonics in the OS keychain (@napi-rs/keyring). The server opens wallet.db on the first wallet operation in each process (any wallet_* tool, or another tool that uses the active wallet account), and at that point runs a silent, idempotent migration:

• For every non-archived accounts row whose mnemonic column is NULL or empty, it attempts to read the mnemonic from the OS keychain under the service name algorand-mcp keyed by the address.

• If found, the mnemonic is copied into the DB column.

• The original keychain entry is left in place as a redundant backup. It is deleted (best effort) only when that account is removed with wallet_remove_account.

After this completes, the DB is the sole source of truth. A row whose mnemonic could not be read is archived in the same step (see below) and is never retried, so a keychain that becomes available later does not bring it back. All new accounts are written directly to the DB; the keychain is never written.

Orphan handling (archive, not delete). If an accounts row exists but its mnemonic isn't in the keychain and isn't already in the DB (e.g., the user copied wallet.db to a new machine without also moving the keychain entries, restored from a partial backup, or installed in Docker where the keychain never existed), that row is unusable for signing. Rather than delete it, the server marks the row as archived (UPDATE accounts SET archived = 1 WHERE mnemonic IS NULL OR mnemonic = ''). Archived rows:

• are hidden from the default wallet_list_accounts response

• never become the active account (the active account is a position in the list of non-archived accounts; if that position is past the end of the list after archiving, it resets to 0, the first remaining account)

• keep their original nickname (a partial unique index idx_active_nickname enforces nickname uniqueness only among active rows, so a new wallet_add_account can reuse the same nickname for a fresh keypair)

• are surfaced via wallet_list_accounts { archived: true } for forensics or future recovery

Archiving is silent at the MCP tool layer. The only diagnostic is a one-line stderr log per failed keychain read ([algorand-mcp] keychain read failed for <addr>…: <msg>), so if a user investigates a false archive they can see whether the keychain threw "no entry" vs "access denied" vs "no DBus" etc.

No user action is required for any of this. No prompts, no env vars, no migration tools.

Schema versions

The DB schema evolves via an idempotent migration that runs when a server process first opens wallet.db (on its first wallet operation). No version number is stored; the version is inferred from the columns present:

The v2→v3 step recreates the accounts table (SQLite cannot drop a column-level UNIQUE constraint via ALTER) and copies data forward with archived = 0. Existing wallets keep working unchanged.

x402 HTTP Payments

x402 is an HTTP-native micropayments protocol. It uses the long-reserved 402 Payment Required status as a real handshake: when a client requests a paid resource without paying, the server returns 402 with a PAYMENT-REQUIRED header (base64-encoded JSON; older servers put the same JSON in the response body) listing what it accepts (networks, assets, amounts, the recipient address). The client constructs a payment, attaches it as an HTTP header, retries the same request, and the server returns 200 with the resource. No API keys, no Stripe webhooks, no accounts to manage — payment is part of the request itself.

This MCP implements the Algorand flavor of x402, where payments are USDC (or native ALGO) transfers on Algorand. Its two payment tools collapse the manual flow (probe → parse → build fee payer → build payment → group → sign → encode → header → retry) into a single tool call. They do not check the asset opt-in, so opt in beforehand (see Prerequisites). Three Bazaar tools (bazaar_list, bazaar_search, bazaar_get_resource_details) browse the catalog of paid APIs served at BAZAAR_BASE_URL.

Protocol shape (Algorand variant)

  Agent (LLM)                  algorand-mcp                   Endpoint                Facilitator
  ──────────                   ────────────                   ────────                ───────────
       │                            │                            │                          │
       │  make_http_request_       │                            │                          │
       │  with_x402 {baseURL,...}  │                            │                          │
       │ ────────────────────────► │  HTTP request              │                          │
       │                            │ ─────────────────────────► │                          │
       │                            │  402 PaymentRequired      │                          │
       │                            │ ◄───────────────────────── │                          │
       │                            │  pick accepts[i] for      │                          │
       │                            │  Algorand network          │                          │
       │                            │  build fee-payer + payment │                          │
       │                            │  (atomic group of 2)       │                          │
       │                            │  sign payment leg          │                          │
       │                            │  via agent wallet DB       │                          │
       │                            │  encode unsigned fee-payer │                          │
       │                            │  base64 PAYMENT-SIGNATURE  │                          │
       │                            │ ─────────────────────────► │                          │
       │                            │  HTTP request +            │  forward + settle        │
       │                            │  PAYMENT-SIGNATURE         │ ───────────────────────► │
       │                            │                            │  sign fee-payer,         │
       │                            │                            │  submit atomic group     │
       │                            │  200 + resource            │ ◄─────────────────────── │
       │                            │ ◄───────────────────────── │                          │
       │ ◄─ { result, paid: {...}}│                            │                          │
       │                            │                            │                          │

What's different from the Coinbase/EVM version

1. Same V2 header, Algorand payload. The payment travels in the x402 V2 PAYMENT-SIGNATURE header (V2 uses it on every chain; X-PAYMENT was the V1 name). The header body is base64-encoded JSON with x402Version (2), scheme, network (a CAIP-2 identifier like algorand:wGHE2Pw… for mainnet), a payload holding an Algorand transaction group (paymentGroup, paymentIndex: 1) instead of an EVM signature, and accepted, a verbatim copy of the accepts[] entry the client chose.

2. Payment is an atomic 2-transaction group. Index 0 is a fee-payer transaction (sender = facilitator, amount = 0, fee = 2000 µAlgo for the whole group); index 1 is the actual USDC ASA transfer (sender = wallet, fee = 0). The wallet signs only index 1 — the facilitator signs index 0 server-side at settlement. The user's wallet pays only the USDC, not even network fees.

3. Network strings are Algorand CAIP-2. This MCP recognizes mainnet (wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=) and testnet (SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=). Endpoints that only accept Base, Solana, or other non-Algorand networks are not satisfiable here and the tool returns a clear error.

Coinbase Wallet MCP compatibility (x402 surface)

The x402 tools — make_http_request_with_x402 and x402_discover_payment_requirements — are intentionally name- and shape-compatible with the Coinbase Wallet MCP's x402 tools. The input parameters (baseURL, path, method, queryParams, body, headers, correlationId, maxAmountPerRequest, paymentRequirements, preferredNetwork, extensions) are the same. The output envelope (result, _atomicUnitsNote) is the same.

What this means in practice:

• Drop-in for Algorand x402. Agents and MCP apps written against the Coinbase Wallet MCP's x402 tools work against this server without any prompt changes — they just hit Algorand x402 endpoints instead of Base/Solana ones.

• Same agent reflexes. Models trained on tool-call traces from the Coinbase ecosystem use these tools correctly on first call. Nothing to relearn.

• Compatibility is scoped to the x402 surface only. The wallet, account, transaction-building, and DEX tools in this MCP are Algorand-specific and do not mirror Coinbase's wallet API. Only make_http_request_with_x402 and x402_discover_payment_requirements are drop-in compatible.

The one parameter that necessarily differs: preferredNetwork takes Algorand names (mainnet | testnet | localnet), because the wallet only signs Algorand transactions. Coinbase's enum lists base | base-sepolia | solana | solana-devnet. The value only chooses among the endpoint's accepts entries on Algorand mainnet and testnet: a value that matches none of them (a non-Algorand name, or localnet, which no CAIP-2 id maps to) is ignored, and the cheapest affordable entry is paid. When the endpoint offers no mainnet or testnet entry, the tool returns an error listing the networks it accepts.

Example — paid weather API

# Step 1 (optional): peek at the cost
x402_discover_payment_requirements {
  "baseURL": "https://example.x402.goplausible.xyz",
  "path": "/weather",
  "method": "GET"
}
# returns: { result: { accepts: [{ scheme: "exact", network: "algorand:SGO1...",
#                                  amount: "100", asset: "10458941",
#                                  payTo: "AAAA...", extra: { feePayer: "BBBB..." } }] } }

# Step 2: pay and fetch in one call
make_http_request_with_x402 {
  "baseURL": "https://example.x402.goplausible.xyz",
  "path": "/weather",
  "method": "GET",
  "maxAmountPerRequest": 10000,
  "preferredNetwork": "testnet"
}
# returns: { result: <weather payload>, status: 200, paid: { network: "testnet",
#                                                asset: "10458941",
#                                                amount: "100", payTo: "AAAA..." },
#           paymentResponse: <decoded PAYMENT-RESPONSE header> }

The active wallet account must be opted into the target ASA (e.g. USDC) and hold enough balance to cover the requirement's amount (maxAmountRequired on x402 V1 servers). If it isn't opted in, the payment fails at settlement — opt in first with wallet_optin_asset.

Prerequisites

• An active wallet account exists (wallet_get_info to verify)

• That account is opted into the payment asset (USDC mainnet ASA 31566704, testnet ASA 10458941)

• The account has enough of the payment asset for the requirement's amount (V1: maxAmountRequired)

• The endpoint's accepts[] includes at least one entry with an Algorand network the MCP recognizes (mainnet or testnet), within maxAmountPerRequest when you set it

• The entry the tool picks names the facilitator's fee payer in extra.feePayer; the tool always builds the fee-payer group and refuses an entry without one

Optional Environment Variables

Environment variables are only needed for special setups. Pass them via the env block in your MCP config.

Example: localnet (AlgoKit)

{
  "mcpServers": {
    "algorand-mcp": {
      "command": "node",
      "args": ["/path/to/algorand-mcp/dist/index.js"],
      "env": {
        "ALGORAND_LOCALNET_URL": "http://localhost:4001",
        "ALGORAND_TOKEN": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      }
    }
  }
}

Then use "network": "localnet" in your tool calls.

Available Tools

Wallet Tools (10 tools)

See Agent Wallet for full architecture details.

x402 HTTP Payment Tools (5 tools)

See x402 HTTP Payments for the full protocol explanation.

Account Management (8 tools)

Utility Tools (13 tools)

Transaction Tools (18 tools)

Algod Tools (5 tools)

Algod API Tools (13 tools)

Live, current-state reads against an Algod node. Default choice for account/application/asset lookups — the matching indexer endpoints were intentionally disabled to keep the tool surface lean (see Indexer API Tools). Use the indexer family below only when you need historical or filtered queries that algod cannot serve.

Indexer API Tools (10 tools)

Historical / filtered queries against an Algorand Indexer instance. Use these for time-range scans, paginated searches, log retrieval, and creator/holder discovery — anything algod's current-state endpoints cannot answer.

Seven indexer endpoints that duplicated algod equivalents (account-by-id, account assets, account app local states, application by id, application box, application boxes, asset by id) were intentionally disabled. They live commented-out in src/tools/apiManager/indexer/; to re-enable one, uncomment both its tool definition and its handler case in the same file.

NFDomains Tools (6 tools)

NFDomains tools always query the mainnet NFD API (api.nf.domains); the network parameter has no effect on them.

Tinyman AMM Tools (9 tools)

Tinyman tools work on mainnet and testnet only; "network": "localnet" is rejected.

Haystack Router Tools (3 tools)

Haystack Router tools work on mainnet and testnet only; "network": "localnet" is rejected.

Pera Wallet Tools (3 tools)

Pera Wallet tools are mainnet only — the Pera public API does not support testnet or localnet.

Alpha Arcade Tools (14 tools)

Trade on-chain prediction markets (YES/NO outcomes) denominated in USDC. All prices and quantities use microunits (1,000,000 = $1.00 or 1 share). Read-only tools work without a wallet; trading tools require an active wallet account. Alpha Arcade runs on mainnet only: pass "network": "mainnet", since the matcher app and USDC asset IDs are mainnet IDs and the server defaults to testnet.

Optional env var: ALPHA_API_KEY — needed for reward market data. ALPHA_API_BASE_URL — custom API endpoint (default: https://platform.alphaarcade.com/api).

ARC-90 URI Tools (1 tool)

Knowledge Tools (1 tool)

Resources

The server exposes the 13 knowledge resources below. Each returns JSON (application/json): algorand://knowledge/taxonomy returns all 12 categories, and every other URI returns one category with the keys of its documents. Pass those keys to get_knowledge_doc to read the documents. There are no wallet resources; the wallet is reached through the Wallet Tools.

Knowledge Resources

Document keys use : as the separator (for example arcs:specs:arc-0020.md); pass them to get_knowledge_doc as listed. On disk each document is stored with ~ in place of : (arcs~specs~arc-0020.md) so the file names are valid on Windows; the tool maps keys to files and does not accept the on-disk names.

Project Structure

algorand-mcp/
├── src/                         # TypeScript source
│   ├── index.ts                 # Server entry point
│   ├── networkConfig.ts         # Hardcoded network URLs and client factories
│   ├── algorand-client.ts       # Re-exports from networkConfig
│   ├── env.ts                   # Legacy env shim (unused)
│   ├── types.ts                 # Zod schemas (unused: imported nowhere)
│   ├── resources/               # MCP Resources (knowledge documents only)
│   │   ├── index.ts             # ResourceManager: resources/list and resources/read
│   │   └── knowledge/           # Documentation taxonomy
│   │       ├── taxonomy/        # One Markdown file per document key (':' written as '~')
│   │       └── taxonomy-categories/  # Category indexes (JSON) listing the document keys
│   ├── tools/                   # MCP Tools
│   │   ├── index.ts             # Re-exports every manager
│   │   ├── commonParams.ts      # Network + pagination schema fragments
│   │   ├── walletManager.ts     # Agent wallet (SQLite-backed)
│   │   ├── x402Manager.ts       # x402 HTTP payments + Bazaar discovery
│   │   ├── accountManager.ts    # Account operations
│   │   ├── utilityManager.ts    # Utility functions
│   │   ├── algodManager.ts      # TEAL compile, simulate, submit
│   │   ├── arc90Manager.ts      # ARC-90 payment URIs + QR codes (QRClaw)
│   │   ├── knowledgeManager.ts  # Knowledge document access
│   │   ├── transactionManager/  # Transaction building
│   │   │   ├── index.ts         # Routes make_* and the group/sign/encode/decode tools
│   │   │   ├── accountTransactions.ts
│   │   │   ├── assetTransactions.ts
│   │   │   ├── appTransactions/
│   │   │   └── generalTransaction.ts
│   │   └── apiManager/          # API integrations
│   │       ├── index.ts         # Routes api_* / alpha_* + pagination
│   │       ├── algod/           # Algod API
│   │       ├── indexer/         # Indexer API
│   │       ├── nfd/             # NFDomains
│   │       ├── tinyman/         # Tinyman AMM (uses vendor/tinyman-js-sdk)
│   │       ├── hayrouter/       # Haystack Router DEX aggregator
│   │       ├── pera/            # Pera Wallet verified assets
│   │       └── alpha/           # Alpha Arcade prediction markets
│   └── utils/
│       └── responseProcessor.ts # Pagination and formatting
├── vendor/                      # Third-party code shipped with the package
│   └── tinyman-js-sdk/          # Tinyman JS SDK 5.1.5, compiled and unmodified (MIT, LICENSE included)
├── tests/                       # Test suite
│   ├── helpers/                 # Shared test utilities
│   │   ├── mockFactories.ts     # Mock algod/indexer/keychain factories
│   │   ├── testConfig.ts        # Category enable/disable logic
│   │   ├── e2eSetup.ts          # getE2EAccount() + invokeTool() (copy of the server dispatch)
│   │   └── testConstants.ts     # Well-known testnet addresses and asset IDs
│   ├── unit/                    # 11 unit test suites (mocked, fast)
│   ├── e2e/                     # 11 E2E test suites (live testnet)
│   │   ├── globalSetup.ts       # Account provisioning + fund-check
│   │   └── globalTeardown.ts    # Prints a completion message
│   └── jest.config.e2e.js       # E2E-specific Jest config
├── skills/                      # Agent skills (Algorand, x402, Alpha Arcade, Haystack Router)
├── dist/                        # Compiled output
├── AGENTS.md                    # Guide for agents using the tools
├── .env.example                 # Environment variables the server reads (all optional)
├── jest.config.js               # Unit test Jest config
├── tsconfig.json                # Production TypeScript config
├── tsconfig.test.json           # Test TypeScript config
└── package.json

Response Format

All tool responses follow the MCP content format. Responses from the api_* and alpha_* tools are wrapped in { "data": ... } and paginated when an array or object in them exceeds itemsPerPage (default: the ITEMS_PER_PAGE env var, else 10):

{
  "data": { ... },
  "metadata": {
    "totalItems": 100,
    "itemsPerPage": 10,
    "currentPage": 1,
    "totalPages": 10,
    "hasNextPage": true,
    "pageToken": "cGFnZV8y",
    "arrayField": "transactions"
  }
}

Pass pageToken from a previous response to fetch the next page, and set itemsPerPage on the call to control page size. Both apply only to the api_* and alpha_* tools; pageToken is read by the server although no tool schema declares it. The other tools list itemsPerPage in their schemas but return unpaginated results.

Development

# Install dependencies
npm install

# Type-check
npm run typecheck

# Build
npm run build

# Clean build output
npm run clean

Testing

The project has a comprehensive dual-layer test suite: fast unit tests (mocked, no network) and real E2E tests (live testnet). Both use Jest 29 with ts-jest and ESM support.

Quick start

npm test                    # Unit tests (fast, no network)
npm run test:e2e            # E2E tests (testnet, generates account + fund link)
npm run test:all            # Both

Unit tests

Unit tests cover 11 of the 15 tool categories with fully mocked network dependencies; x402, Haystack Router, Pera Wallet and Alpha Arcade have no unit suite yet. They run in parallel and finish in ~5 seconds. No environment variables or funded accounts are needed.

npm test

Coverage: 11 suites, 140+ tests covering success paths, error handling, and edge cases for the categories below.

How mocking works

Unit tests use jest.unstable_mockModule() (ESM-compatible) to intercept imports before they load. The shared tests/helpers/mockFactories.ts provides:

• setupNetworkMocks() — Replaces algorand-client.ts with mock algod/indexer clients that return deterministic responses without any network calls.

• createKeychainMock() — Replaces @napi-rs/keyring with an in-memory Map, so wallet tests work without an OS keychain.

• Fluent Proxy mocks — Algorand's Indexer SDK uses a builder pattern (.searchForAssets().limit(5).do()). The mock factory uses ES Proxy objects that return themselves for any chained method and resolve when .do() is called.

E2E tests

E2E tests call tool handlers directly against Algorand testnet (via AlgoNode public nodes); the NFD suite calls the mainnet NFD API and the ARC-90 suite calls the live QRClaw service. They run serially to avoid rate-limiting.

The wallet suite changes your real agent wallet: it adds an account to ~/.algorand-mcp/wallet.db, makes it the active account and then removes it, which can leave a different account active than before. The path comes from your home directory and has no separate setting, so run E2E tests with HOME pointing at a scratch directory, e.g. HOME=$(mktemp -d) npm run test:e2e.

npm run test:e2e

On first run (no mnemonic provided), the test setup:

1. Generates a new Algorand account

2. Prints the address and mnemonic

3. Prints a fund link: https://lora.algokit.io/testnet/fund

4. Runs all tests (unfunded tests still pass)

To run with a funded account:

E2E_MNEMONIC="word1 word2 ... word25" npm run test:e2e

Coverage: 11 suites, 35+ tests covering real network interactions.

Category activation

E2E tests can be selectively enabled by category via environment variables. By default all categories are enabled.

Enable specific categories

E2E_WALLET=1 npm run test:e2e            # Only wallet tests
E2E_ALGOD=1 E2E_UTILITY=1 npm run test:e2e  # Algod + utility tests

Available category flags

Important: Setting any individual flag (e.g. E2E_WALLET=1) disables all other categories unless E2E_ALL=1 is also set.

Enable categories by tool name

E2E_TOOLS=ping,validate_address npm run test:e2e

The E2E_TOOLS variable accepts a comma-separated list of tool names and enables the whole category of each named tool (here, all utility tests): the suites filter by category, not by tool. Other categories stay disabled unless their own flag or E2E_ALL=1 is set.

Test file structure

tests/
├── helpers/
│   ├── mockFactories.ts       # Mock algod/indexer/keychain factories
│   ├── testConfig.ts          # Category enable/disable logic
│   ├── e2eSetup.ts            # getE2EAccount() + invokeTool() (copy of the server dispatch)
│   └── testConstants.ts       # Well-known testnet addresses and asset IDs
├── unit/                      # 11 unit test files (*.test.ts)
│   ├── accountManager.test.ts
│   ├── utilityManager.test.ts
│   ├── walletManager.test.ts
│   ├── transactionManager.test.ts
│   ├── algodManager.test.ts
│   ├── apiAlgod.test.ts
│   ├── apiIndexer.test.ts
│   ├── apiNfd.test.ts
│   ├── apiTinyman.test.ts
│   ├── arc90Manager.test.ts
│   └── knowledgeManager.test.ts
├── e2e/                       # 11 E2E test files (*.e2e.test.ts)
│   ├── globalSetup.ts         # Account provisioning + fund-check
│   ├── globalTeardown.ts      # Prints a completion message
│   ├── account.e2e.test.ts
│   ├── utility.e2e.test.ts
│   ├── wallet.e2e.test.ts
│   ├── transaction.e2e.test.ts
│   ├── algod.e2e.test.ts
│   ├── algodApi.e2e.test.ts
│   ├── indexerApi.e2e.test.ts
│   ├── nfd.e2e.test.ts
│   ├── tinyman.e2e.test.ts
│   ├── arc90.e2e.test.ts
│   └── knowledge.e2e.test.ts
└── jest.config.e2e.js         # E2E-specific Jest config

Jest configuration

Writing new tests

Unit test template:

import { jest } from '@jest/globals';
import { setupNetworkMocks } from '../helpers/mockFactories.js';

jest.unstable_mockModule('../../src/algorand-client.js', () => setupNetworkMocks());

const { YourManager } = await import('../../src/tools/yourManager.js');

describe('YourManager', () => {
  it('does something', async () => {
    const result = await YourManager.handleTool('tool_name', { arg: 'value' });
    const data = JSON.parse(result.content[0].text);
    expect(data.field).toBeDefined();
  });
});

E2E test template (for a new category, add it to TOOL_CATEGORIES and toolCategoryMap in tests/helpers/testConfig.ts, and make sure invokeTool() in tests/helpers/e2eSetup.ts routes its tools: that copy of the server's dispatch has no routes yet for the x402, bazaar_*, alpha_*, encode_unsigned_transaction and decode_signed_transaction tools):

import { describeIf, testConfig } from '../helpers/testConfig.js';
import { invokeTool, parseToolResponse } from '../helpers/e2eSetup.js';

describeIf(testConfig.isCategoryEnabled('your-category'))('Your Tools (E2E)', () => {
  it('does something on testnet', async () => {
    const data = parseToolResponse(
      await invokeTool('tool_name', { arg: 'value', network: 'testnet' }),
    );
    expect(data.field).toBeDefined();
  });
});

Dependencies

• algosdk v3 — Algorand JavaScript SDK

• @modelcontextprotocol/sdk — MCP TypeScript SDK

• @napi-rs/keyring — Native OS keychain access (macOS Keychain, Linux libsecret, Windows Credential Manager). Used as a backward-compatibility read fallback for accounts created by pre-DB-migration installs, and for a best-effort cleanup of any leftover keychain entry when an account is removed; new mnemonics are written only to wallet.db.

• sql.js — Embedded SQLite (WASM) for the agent wallet: accounts, their mnemonics and the active account, persisted to ~/.algorand-mcp/wallet.db

• @noble/curves — Pure JS Ed25519 for raw data signing (wallet_sign_data)

• @txnlab/haystack-router — Haystack Router SDK (DEX aggregator quotes and swaps)

• @alpha-arcade/sdk 0.5.2 (pinned) — Alpha Arcade prediction market SDK

• base64-js — Base64 encoding, required by the vendored Tinyman SDK

• zod — Schema library that the MCP SDK requires; listed here so every install gets a patched 4.x release (CVE-2023-54404). This server checks tool arguments in its own handlers, not with Zod.

Shipped with the package:

• Tinyman JS SDK 5.1.5 — Tinyman AMM SDK, compiled and unmodified, in vendor/tinyman-js-sdk/ with its MIT license. It replaces the @tinymanorg/tinyman-js-sdk npm package, whose deprecated uuid@10 dependency fails dependency security scans; see VENDORED.md.

License

MIT