Algorand MCP

Algorand MCP服务器

](https://www.npmjs.com/package/@goplausible/algorand-mcp) ](https://www.npmjs.com/package/@goplausible/algorand-mcp) 

全面 模型上下文协议（MCP） 服务器，使AI代理和LLM能够完全访问Algorand区块链。建造于 很可能.

Algorand是一个碳负、纯权益证明的第1层区块链，具有即时终结性、低费用，并内置了对智能合约（AVM）、标准资产（ASA）和原子交易的支持。

什么是MCP？

模型上下文协议 是一个开放标准，允许人工智能应用程序连接到外部工具和数据源。该服务器将Algorand区块链操作作为MCP工具公开，任何兼容的AI客户端都可以使用这些工具——Claude Desktop、Claude Code、Cursor、Windsurf等。

特性

• 通过操作系统钥匙链进行安全的钱包管理——私钥永远不会暴露给代理或LLM
• 钱包账户昵称、津贴和每日限额，用于安全支出控制
• 帐户创建、密钥管理和密钥更新
• 交易构建、签署和提交（支付、资产、应用程序、密钥注册）
• 原子事务组
• TEAL编译和拆卸
• 完整的Algod和Indexer API访问
• NFDomains（NFD）名称服务集成
• Algorand的x402和AP2插件
• Tinyman AMM集成（池、掉期、流动性）
• Haystack Router DEX聚合（Tinyman、Pact、Folks之间的最佳价格互换）
• Alpha Arcade预测市场交易（浏览市场、订单簿、限价/市价单、头寸、索赔）
• ARC-26 URI和二维码生成
• Algorand知识库，具有完整的开发人员文档分类
• 按工具调用网络选择（主网、测试网、本地网）和分页

需求

• Node.js v20或更高版本
• npm、pnpm或yarn

安装

来自npm

npm install -g @goplausible/algorand-mcp

来源

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

MCP配置

服务器运行超时 标准。有三种方法可以调用它——选择适合您设置的方法：

不需要环境变量 用于标准使用。每次工具调用都会动态处理网络选择、分页和节点URL。

______________________________________________________________________

龙虾

无需手动配置--安装 @goplausible/openclaw-algorand-plugin npm包和Algorand MCP服务器自动配置：

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

______________________________________________________________________

克劳德桌面版

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

使用npx：

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

使用全局安装：

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

使用绝对路径：

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

______________________________________________________________________

克劳德代码

创建 .mcp.json 在项目根目录（项目范围）中，或 ~/.claude.json （用户范围）：

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

或者以交互方式添加：

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

______________________________________________________________________

光标

通过添加 设置>MCP服务器，或编辑 .cursor/mcp.json 在项目根目录中：

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

______________________________________________________________________

帆板运动

通过添加 设置>MCP，或编辑 ~/.codeium/windsurf/mcp_config.json:

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

______________________________________________________________________

VS代码/GitHub副本

编辑 .vscode/mcp.json 在您的工作区根目录中，或打开 设置>MCP服务器:

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

______________________________________________________________________

克莱恩

通过添加 MCP服务器 Cline侧边栏中的面板，或编辑 ~/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命令行界面

创建 .codex/mcp.json 在您的项目根目录中或 ~/.codex/mcp.json 对于全球范围：

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

______________________________________________________________________

打开代码

编辑 ~/.config/opencode/config.json:

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

______________________________________________________________________

任何兼容MCP的客户端

服务器使用标准MCP stdio协议。对于上面未列出的任何客户端，请使用以下配置：

• 命令： npx （或 algorand-mcp 如果全局安装，或 node /path/to/dist/index.js)
• Args： ["@goplausible/algorand-mcp"] （适用于npx）
• 运输： stdio

网络选择

每个工具都接受一个可选 network 参数： "mainnet" （默认）， "testnet"，或 "localnet"。Algod和Indexer URL是通过以下方式为主网和测试网内置的 .

示例工具调用：

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

如果不 network 提供，工具默认为 主网.

分页

API响应自动分页。每个工具都接受一个可选 itemsPerPage 参数（默认值：10）。通过 pageToken 从之前的响应中提取下一页。

安全钱包

建筑

钱包系统有两层存储，每层都有不同的安全作用：

私钥材料从未出现在工具响应、MCP配置文件、环境变量或日志中。 代理只看到地址、公钥和已签名的事务blob。

运作原理

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

1. 帐户创建 (wallet_add_account)--生成一个密钥对，将助记符存储在操作系统密钥链中，并将元数据（昵称、支出限制）存储在SQLite中。退货 仅 地址和公钥。
2. 活动帐户 --一次只有一个帐户处于活动状态。 wallet_switch_account 通过昵称或索引进行更改。所有签名和查询工具都在活动帐户上运行。
3. 交易签名 (wallet_sign_transaction)--检查每笔交易和每日支出限制，从密钥链中检索密钥，在内存中签名，丢弃密钥。仅返回已签名的blob。
4. 数据签名 (wallet_sign_data)--使用原始Ed25519通过以下方式对任意十六进制数据进行签名 @noble/curves 库（无Algorand SDK前缀）。可用于链下身份验证。
5. 资产选择加入 (wallet_optin_asset)--一步创建、签署和提交活动帐户的选择加入交易。

支出限额

每个帐户都有两个可配置的限制（在microAlgos中，0=无限制）：

• allowance --每笔交易的最大金额。拒绝任何超过此值的交易。
• dailyAllowance --所有交易中每个日历日的最大总支出。午夜自动重置。在SQLite中跟踪。

平台钥匙链支持

钥匙链后端由提供 @napi-rs/keyring （基于Rust的预构建二进制文件）：

所有凭据都存储在服务名称下 algorand-mcp。您可以使用操作系统钥匙链应用程序（例如macOS上的钥匙链访问）检查它们。

可选环境变量

只有特殊设置才需要环境变量。通过 env MCP配置中的块。

示例：本地网（AlgoKit）

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

然后使用 "network": "localnet" 在您的工具调用中。

可用工具

钱包工具（10个工具）

看 安全钱包 了解完整的架构细节。

账户管理（8个工具）

实用工具（13个工具）

交易工具（18个工具）

算法工具（5个工具）

Algod API工具（13个工具）

实时、当前状态读取Algod节点。 帐户/应用程序/资产查找的默认选择 --有意禁用匹配的索引器端点以保持刀具表面倾斜（请参见 .notes/redunda-tools-report.md).仅当您需要algod无法提供的历史查询或筛选查询时，才使用下面的索引器系列。

索引器API工具（10个工具）

对Algorand Indexer实例的历史/过滤查询。将这些用于时间范围扫描、分页搜索、日志检索和创建者/持有者发现——任何algod当前状态端点都无法回答的问题。

故意禁用了七个重复算法等效项的索引器端点（逐个id的帐户、帐户资产、帐户应用程序本地状态、逐个id的应用程序、应用程序框、应用程序盒、逐个id资产）。他们在现场发表了评论 src/tools/apiManager/indexer/ 如果需要，可以在一个地方重新启用。

NFDomains工具（6个工具）

Tinyman AMM工具（9个工具）

Haystack路由器工具（3个工具）

Pera钱包工具（3个工具）

Pera钱包工具 仅限主网 -Pera公共API不支持testnet或localnet。

阿尔法街机工具（14个工具）

以美元计价的连锁预测市场交易（是/否结果）。所有价格和数量均使用微单位（1000000=1.00美元或1股）。只读工具无需钱包即可使用；交易工具需要一个活跃的钱包账户。

可选环境变量： ALPHA_API_KEY --需要奖励市场数据。 ALPHA_API_BASE_URL -自定义API端点（默认值： https://platform.alphaarcade.com/api).

ARC-26 URI工具（1个工具）

知识工具（1个工具）

资源

服务器公开MCP资源以进行直接数据访问。钱包资源在 安全钱包 上面的部分。

知识资源

项目结构

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                 # Shared types (Zod schemas)
│   ├── resources/               # MCP Resources
│   │   ├── knowledge/           # Documentation taxonomy
│   │   └── wallet/              # Wallet resources
│   ├── tools/                   # MCP Tools
│   │   ├── commonParams.ts      # Network + pagination schema fragments
│   │   ├── walletManager.ts     # Secure wallet (keychain + SQLite)
│   │   ├── accountManager.ts    # Account operations
│   │   ├── utilityManager.ts    # Utility functions
│   │   ├── algodManager.ts      # TEAL compile, simulate, submit
│   │   ├── arc26Manager.ts      # ARC-26 URI generation
│   │   ├── knowledgeManager.ts  # Knowledge document access
│   │   ├── transactionManager/  # Transaction building
│   │   │   ├── accountTransactions.ts
│   │   │   ├── assetTransactions.ts
│   │   │   ├── appTransactions/
│   │   │   └── generalTransaction.ts
│   │   └── apiManager/          # API integrations
│   │       ├── algod/           # Algod API
│   │       ├── indexer/         # Indexer API
│   │       ├── nfd/             # NFDomains
│   │       ├── tinyman/         # Tinyman AMM
│   │       ├── hayrouter/       # Haystack Router DEX aggregator
│   │       ├── pera/            # Pera Wallet verified assets
│   │       └── alpha/           # Alpha Arcade prediction markets
│   └── utils/
│       └── responseProcessor.ts # Pagination and formatting
├── tests/                       # Test suite
│   ├── helpers/                 # Shared test utilities
│   │   ├── mockFactories.ts     # Mock algod/indexer/keychain factories
│   │   ├── testConfig.ts        # Category enable/disable logic
│   │   ├── e2eSetup.ts          # E2E account provisioning + invokeTool()
│   │   └── 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    # Cleanup
│   └── jest.config.e2e.js       # E2E-specific Jest config
├── dist/                        # Compiled output
├── jest.config.js               # Unit test Jest config
├── tsconfig.json                # Production TypeScript config
├── tsconfig.test.json           # Test TypeScript config
└── package.json

响应格式

所有工具响应均遵循MCP内容格式。当数据集超过时，API响应包括自动分页 itemsPerPage （默认值10）：

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

通过 pageToken 从之前的响应中提取下一页。集 itemsPerPage 在任何工具调用中控制页面大小。

发展

# Install dependencies
npm install

# Type-check
npm run typecheck

# Build
npm run build

# Clean build output
npm run clean

测试

快速开始

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

单元测试

单元测试涵盖了所有11个具有完全模拟网络依赖关系的工具类别。他们平行奔跑，约5秒后结束。不需要环境变量或资金账户。

npm test

新闻报道： 11个套件，75+个测试，涵盖每个工具类别的成功路径、错误处理和边缘情况。

嘲讽是如何运作的

单元测试使用 jest.unstable_mockModule() （ESM兼容）在加载之前拦截导入。共享 tests/helpers/mockFactory.ts 提供：

• setupNetworkMocks() --替换 algorand-client.ts 使用模拟algod/indexer客户端，无需任何网络调用即可返回确定性响应。
• createKeychainMock() --替换 @napi-rs/keyring 在记忆中 Map，因此钱包测试在没有操作系统钥匙链的情况下工作。
• Fluent代理模拟 --Algorand的Indexer SDK使用构建器模式(.searchForAssets().limit(5).do()).模拟工厂使用ES Proxy 为任何链式方法返回自身并在以下情况下解析的对象 .do() 被称为。

E2E测试

E2E测试直接调用工具处理程序 Algorand测试网 （通过 公共节点）。它们连续运行以避免速率限制。

npm run test:e2e

首次运行时（未提供助记符），测试设置：

1. 生成新的Algorand帐户
2. 打印地址和助记符
3. 打印基金链接：https://lora.algokit.io/testnet/fund
4. 运行所有测试（无资金支持的测试仍然通过）

要使用资金账户运行：

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

新闻报道： 11个套件，35+个测试，涵盖真实的网络交互。

类别激活

E2E测试可以通过环境变量按类别或单个工具选择性启用。 默认情况下，所有类别都已启用。

启用特定类别

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

可用类别标志

重要提示： 设置任何单个标志（例如。 E2E_WALLET=1)禁用所有其他类别，除非 E2E_ALL=1 也设置了。

启用特定工具

E2E_TOOLS=ping,validate_address npm run test:e2e

这 E2E_TOOLS 变量接受逗号分隔的工具名称列表。只有这些特定工具的测试才会运行。

测试文件结构

tests/
├── helpers/
│   ├── mockFactories.ts       # Mock algod/indexer/keychain factories
│   ├── testConfig.ts          # Category enable/disable logic
│   ├── e2eSetup.ts            # E2E account provisioning + invokeTool()
│   └── 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
│   ├── arc26Manager.test.ts
│   └── knowledgeManager.test.ts
├── e2e/                       # 11 E2E test files (*.e2e.test.ts)
│   ├── globalSetup.ts         # Account provisioning + fund-check
│   ├── globalTeardown.ts      # Cleanup
│   ├── 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
│   ├── arc26.e2e.test.ts
│   └── knowledge.e2e.test.ts
└── jest.config.e2e.js         # E2E-specific Jest config

Jest配置

编写新测试

单元测试模板：

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测试模板：

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();
  });
});

依赖项

• algosdk v3——Algorand JavaScript SDK
• @模型上下文协议/sdk --MCP TypeScript SDK
• @napi rs/钥匙圈 --本机操作系统密钥链访问（macOS密钥链、Linux libsecret、Windows凭据管理器）
• sql.js --用于钱包元数据持久化的嵌入式SQLite（WASM）
• @贵族/曲线 --纯JS Ed25519用于原始数据签名(wallet_sign_data)
• @tinymanorg/tinymanjs-sdk --Tinyman AMM SDK
• @阿尔法街机/sdk --阿尔法街机预测市场SDK
• 黄道带 --运行时类型验证
• 二维码 --ARC-26二维码生成

许可证

麻省理工学院