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.

Features

• Secure wallet management via OS keychain — private keys never exposed to agents or LLMs
• 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 and AP2 toolins 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.

Secure Wallet

Architecture

The wallet system has two layers of storage, each with a distinct security role:

Layer	What it stores	Where	Encryption
OS Keychain	Mnemonics (secret keys)	macOS Keychain / Linux libsecret / Windows Credential Manager	OS-managed, hardware-backed where available
Embedded SQLite	Account metadata (nicknames, active-account index)	~/.algorand-mcp/wallet.db	Plaintext (no secrets)

Private key material never appears in tool responses, MCP config files, environment variables, or logs. The agent only sees addresses, public keys, and signed transaction blobs.

How it works

  Agent (LLM)                    MCP Server                     Storage
  ──────────                     ──────────                     ───────
       │                              │                              │
       │  wallet_add_account          │                              │
       │  { nickname: "main" }        │                              │
       │ ──────────────────────────►  │  generate keypair            │
       │                              │  store mnemonic ──────────►  │  OS Keychain (encrypted)
       │                              │  store metadata ──────────►  │  SQLite (nickname)
       │  ◄─ { address, publicKey }   │                              │
       │                              │                              │
       │  wallet_sign_transaction     │                              │
       │  { transaction: {...} }      │                              │
       │ ──────────────────────────►  │  retrieve mnemonic ◄──────  │  OS Keychain
       │                              │  sign in memory              │
       │  ◄─ { txID, blob }          │  (key discarded)             │
       │                              │                              │

1. Account creation (wallet_add_account) — Generates a keypair, stores the mnemonic in the OS keychain, and stores the nickname in SQLite. Returns only address and public key.
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) — Retrieves the key from the keychain, signs in memory, discards the key. 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.

Platform keychain support

The keychain backend is provided by @napi-rs/keyring (Rust-based, prebuilt binaries):

Platform	Backend
macOS	Keychain Services (the system Keychain app)
Linux	libsecret (GNOME Keyring) or KWallet
Windows	Windows Credential Manager

All credentials are stored under the service name algorand-mcp. You can inspect them with your OS keychain app (e.g. Keychain Access on macOS).

Optional Environment Variables

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

Variable	Description	Default	When needed
ALGORAND_TOKEN	API token for private/authenticated nodes	""	Connecting to a private Algod/Indexer node
ALGORAND_LOCALNET_URL	Localnet base URL	""	Using network: "localnet" (e.g. http://localhost:4001)
ALPHA_API_KEY	Alpha Arcade API key	""	Accessing reward market data

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 Secure Wallet for full architecture details.

Tool	Description
wallet_add_account	Create a new Algorand account with nickname (returns address + public key only)
wallet_remove_account	Remove an account from the wallet by nickname or index
wallet_list_accounts	List all accounts with nicknames and addresses
wallet_switch_account	Switch the active account by nickname or index
wallet_get_info	Get info for the active account this MCP server owns (keychain-backed): address, public key, balance, opted-in counts. For arbitrary on-chain accounts use api_algod_get_account_info.
wallet_get_assets	Get all ASA holdings for the active account this MCP server owns. For arbitrary on-chain accounts use api_algod_get_account_info or api_algod_get_account_asset_info.
wallet_sign_transaction	Sign a single transaction with the active account
wallet_sign_transaction_group	Sign a group of transactions with the active account (auto-assigns group ID)
wallet_sign_data	Sign arbitrary hex data with raw Ed25519 (noble, no SDK prefix)
wallet_optin_asset	Opt the active account into an asset (creates, signs, and submits)

Account Management (8 tools)

Tool	Description
create_account	Create a new Algorand account (returns address + mnemonic in the clear)
rekey_account	Rekey an account to a new address
mnemonic_to_mdk	Convert mnemonic to master derivation key
mdk_to_mnemonic	Convert master derivation key to mnemonic
secret_key_to_mnemonic	Convert secret key to mnemonic
mnemonic_to_secret_key	Convert mnemonic to secret key
seed_from_mnemonic	Generate seed from mnemonic
mnemonic_from_seed	Generate mnemonic from seed

Utility Tools (13 tools)

Tool	Description
ping	Server connectivity check and info
validate_address	Check if an Algorand address is valid
encode_address	Encode a public key to an Algorand address
decode_address	Decode an Algorand address to a public key
get_application_address	Get address for a given application ID
bytes_to_bigint	Convert bytes to BigInt
bigint_to_bytes	Convert BigInt to bytes
encode_uint64	Encode uint64 to bytes
decode_uint64	Decode bytes to uint64
verify_bytes	Verify signature against bytes
sign_bytes	Sign bytes with a secret key
encode_obj	Encode object to msgpack
decode_obj	Decode msgpack to object

Transaction Tools (18 tools)

Tool	Description
make_payment_txn	Create a payment transaction
make_keyreg_txn	Create a key registration transaction
make_asset_create_txn	Create an asset creation transaction
make_asset_config_txn	Create an asset configuration transaction
make_asset_destroy_txn	Create an asset destroy transaction
make_asset_freeze_txn	Create an asset freeze transaction
`mak