Algorand Mcp

Algorand MCP Server

[](https://www.npmjs.com/package/@goplausible/algorand-mcp) [](https://www.npmjs.com/package/@goplausible/algorand-mcp) [](https://opensource.org/licenses/MIT)

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.

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
• Full Algod and Indexer API access
• NFDomains (NFD) name service integration
• x402 HTTP micropayments — automatic discovery and one-call paid requests using the active wallet (USDC/ALGO)
• AP2 tooling for Algorand
• 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-26 URI and QR code generation
• Algorand knowledge base with full developer documentation taxonomy
• Per-tool-call network selection (mainnet, testnet, localnet) and pagination

Requirements

• Node.js v20 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:

| Method | Command | When to use | |---|---|---| | npx (recommended) | npx @goplausible/algorand-mcp | No install needed, always latest version | | Global install | algorand-mcp | After npm install -g @goplausible/algorand-mcp | | Absolute path | node /path/to/dist/index.js | Built from source or local clone |

No environment variables are required for standard use. Network selection, pagination, and node URLs are all handled dynamically per tool call.

---

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) or ~/.claude.json (user scope):

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

Or add interactively:

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

Create .codex/mcp.json in your project root or ~/.codex/mcp.json for global scope:

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

---

Open Code

Edit ~/.config/opencode/config.json:

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

---

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 accepts an optional network parameter: "mainnet" (default), "testnet", or "localnet". Algod and Indexer URLs are built-in for mainnet and testnet via AlgoNode.

Example tool call:

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

If no network is provided, tools default to mainnet.

Pagination

API responses are automatically paginated. Every tool accepts an optional itemsPerPage parameter (default: 10). Pass the pageToken from a previous response 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.

| Layer | What it stores | Where | |---|---|---| | SQLite (wallet.db) | Account rows (address, public_key, nickname, mnemonic, created_at) and the active-account index | ~/.algorand-mcp/wallet.db (mode 0600) |

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=         │
       │                              │  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). On first startup after upgrading, the server runs a one-shot, silent migration:

• For every 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; nothing is deleted.

After this completes, the DB is the sole source of truth. The keychain is consulted only as a fallback if the DB still has a NULL mnemonic for an address (e.g., the keychain was unavailable during startup and became available later). All new accounts created after the upgrade are written directly to the DB and never touch the keychain.

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 index is clamped to the end of the remaining active list, or reset to 0 if no active accounts remain)
• 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 …: ), 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 additively via an idempotent migration that runs at startup:

| Version | Change | |---|---| | v1 | initial — accounts columns: id, address, public_key, nickname (UNIQUE), created_at | | v2 | added mnemonic TEXT column | | v3 | added archived INTEGER NOT NULL DEFAULT 0 column; dropped the column-level UNIQUE on nickname and replaced it with CREATE UNIQUE INDEX idx_active_nickname ON accounts(nickname) WHERE archived = 0 so archived rows can keep their original nicknames without blocking reuse |

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 JSON 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. It exposes two tools that collapse the seven-step manual flow (probe → parse → opt-in check → build fee payer → build payment → group → sign → encode → header → retry) into a single tool call.

Protocol shape (Algorand variant)

  Agent (LLM)                  algorand-mcp                   Endpoint                Facilitator
  ──────────                   ────────────                   ────────                ───────────
       │                            │                            │                          │
       │  make_http_request_       │                            │                          │
       │  with_x402 { url, ... }   │                            │                          │
       │ ────────────────────────► │  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,         │
       │

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [GoPlausible](https://github.com/GoPlausible)
- **Source:** [GoPlausible/algorand-mcp](https://github.com/GoPlausible/algorand-mcp)
- **License:** MIT
- **Homepage:** https://GoPlausible.com

Install and usage instructions live in the source repository linked above.