multiversx-sc-mcp

MCP server for MultiversX smart contract development — deploy, upgrade, verify, query, simulate, and test contracts directly from AI agents.

41 tools + 8 AI workflows for full blockchain and smart contract interaction.

Features

Smart Contract Tools (mvx_sc_*)

Development Tools (mvx_sc_*)

General Blockchain Tools (mvx_*)

Token Management (mvx_token_*)

Batch Transfers

Relayed Transactions

Setup

AI Workflows (MCP Prompts)

Built-in guided workflows that orchestrate the tools above:

Key Capabilities

• ABI auto-discovery — just provide a contract address; ABI is fetched automatically for verified contracts
• Human-readable I/O — pass native values, get decoded results
• Multi-network — mainnet, testnet, devnet with per-request override
• Zero config for reads — no wallet needed for queries, storage, or ABI inspection
• Safe by default — write operations require explicit wallet configuration
• Mainnet safety rails — all write operations on mainnet require explicit user confirmation
• Address validation — all inputs validated before network calls
• Timeout protection — all network calls have 30s timeout (no hanging)
• Cross-linked workflows — each workflow suggests next steps and related workflows

Quick Start

Claude Code

claude mcp add multiversx-sc -- npx -y multiversx-sc-mcp

Manual Setup

git clone https://github.com/psorinionut/multiversx-sc-mcp.git
cd multiversx-sc-mcp
npm install

Then add to your Claude Code, Claude Desktop, or Cursor config:

{
  "mcpServers": {
    "multiversx-sc": {
      "command": "node",
      "args": ["/path/to/multiversx-sc-mcp/dist/index.js"],
      "env": {
        "MULTIVERSX_NETWORK": "mainnet"
      }
    }
  }
}

Global Install

npm install -g multiversx-sc-mcp
claude mcp add multiversx-sc -- multiversx-sc-mcp

First-Time Setup

After installing, the agent will offer to configure permissions. Choose:

• Safe mode: Read-only tools auto-approved, write tools need confirmation
• Allow all: All tools auto-approved (for dev/testnet only)

Configuration

Environment Variables

Usage Examples

Query a contract view

"What are the reserves on the WEGLD/USDC pair?"
→ mvx_sc_query(address, "getReservesAndTotalSupply")

Read contract storage

"What's the LP token for pair erd1qqq...?"
→ mvx_sc_storage(address, "lpTokenIdentifier")

Search for a contract

"Find the xExchange fees collector"
→ mvx_search("xExchange fees collector")

Get token info

"What are the details of WEGLD?"
→ mvx_token_info("WEGLD-bd4d79")

Convert values

"Convert erd1qqq... to hex"
→ mvx_convert(value, from: "bech32", to: "hex")

Build and test a contract

"Build the adder contract"
→ mvx_sc_build(path: "/path/to/adder")

"Run tests"
→ mvx_sc_test(path: "/path/to/adder")

Deploy, verify, and test

→ mvx_sc_deploy(wasmPath, abiPath, network: "testnet")
→ mvx_sc_verify(address, packagedSrc, dockerImage)
→ mvx_sc_verify_status(taskId)
→ mvx_test_contract prompt for automated testing

Safe upgrade flow

→ mvx_upgrade_flow prompt (pre-flight checks, mainnet confirmation, post-upgrade verification)

Simulate before sending

"Simulate calling addLiquidity on pair erd1qqq..."
→ mvx_sc_simulate(address, "addLiquidity", args, gasLimit)

Issue a fungible token

"Issue a new fungible token called MyToken with ticker MTK, 18 decimals, 1M supply"
→ mvx_token_issue_fungible(name: "MyToken", ticker: "MTK", initialSupply: "1000000", decimals: 18, network: "devnet")

Issue an NFT collection and create an NFT

"Create an NFT collection called MyArt with ticker MART"
→ mvx_token_issue_nft(name: "MyArt", ticker: "MART", network: "devnet")

"Mint NFT #1 in collection MART-ab1234"
→ mvx_token_create_nft(collection: "MART-ab1234", name: "Art Piece #1", royalties: 500, ...)

Batch transfer EGLD

"Send 0.1 EGLD to 5 addresses"
→ mvx_batch_transfer_egld(recipients: [{address: "erd1...", amount: "0.1"}, ...], network: "devnet")

Batch transfer tokens

"Send MEX to 3 addresses"
→ mvx_batch_transfer_tokens(token: "MEX-455c57", recipients: [{address: "erd1...", amount: "100"}, ...])

Relayed transaction

"Send a relayed transaction paying gas for another user"
→ mvx_relayed_transaction(innerSender: "erd1...", receiver: "erd1qqq...", data: "claimRewards", network: "devnet")

Audit a deployed contract

"Audit the contract at erd1qqq..."
→ mvx_audit_onchain prompt (queries views, reads storage, checks ABI, finds vulnerabilities)

How ABI Resolution Works

1. If abiPath is provided → loads from local file
2. If only address is provided → fetches from MultiversX API (/accounts/{addr}/verification)
3. If ABI is found → arguments are encoded/decoded automatically
4. If no ABI → raw mode (hex in, hex out)

ABIs are cached in memory for the session duration.

Architecture

src/
├── index.ts                # MCP server — 41 tools + 8 prompts
├── core/
│   ├── provider.ts         # Network provider factory
│   └── abi-loader.ts       # ABI fetch (API auto-discovery + local + cache)
├── tools/
│   ├── query.ts            # mvx_sc_query
│   ├── storage.ts          # mvx_sc_storage, mvx_sc_storage_keys
│   ├── call.ts             # mvx_sc_call
│   ├── deploy.ts           # mvx_sc_deploy, mvx_sc_upgrade
│   ├── verify.ts           # mvx_sc_verify, mvx_sc_verify_status
│   ├── simulate.ts         # mvx_sc_simulate, mvx_sc_estimate_gas
│   ├── abi.ts              # mvx_sc_abi
│   ├── decode.ts           # mvx_sc_decode
│   ├── account.ts          # mvx_account
│   ├── search.ts           # mvx_search
│   ├── transfer.ts         # mvx_transfer
│   ├── tx-result.ts        # mvx_tx_result
│   ├── token-info.ts       # mvx_token_info
│   ├── network-config.ts   # mvx_network_config
│   ├── convert.ts          # mvx_convert, mvx_format_amount
│   ├── sign-message.ts     # mvx_sign_message
│   ├── verify-message.ts   # mvx_verify_sig
│   ├── native-auth.ts      # mvx_native_auth_decode, mvx_native_auth_generate
│   ├── wallet.ts           # mvx_wallet_new, mvx_wallet_info
│   ├── sc-meta.ts          # mvx_sc_build, mvx_sc_test, mvx_sc_new, mvx_sc_proxy, mvx_sc_compare, mvx_sc_reproducible_build
│   ├── token-management.ts # mvx_token_issue_fungible, mvx_token_issue_nft, mvx_token_issue_sft, mvx_token_issue_meta_esdt, mvx_token_create_nft
│   ├── batch-transfer.ts   # mvx_batch_transfer_egld, mvx_batch_transfer_tokens
│   ├── relayed.ts          # mvx_relayed_transaction
│   └── setup.ts            # mvx_setup
├── prompts/
│   └── index.ts            # 8 AI workflow prompts (load from skills/)
├── utils/
│   ├── networks.ts         # Network URLs, getChainId, getExplorerUrl
│   ├── validation.ts       # Address validation
│   ├── fetch.ts            # fetchWithTimeout wrapper
│   ├── serialize.ts        # Shared value serialization (BigInt, Address, etc.)
│   └── nonce.ts            # Gateway nonce fetching
└── skills/                  # Standalone markdown workflow files
    ├── mvx-orchestrator.md
    ├── mvx-audit-onchain.md
    ├── mvx-audit-source.md
    ├── mvx-test-contract.md
    ├── mvx-deploy-flow.md
    ├── mvx-upgrade-flow.md
    ├── mvx-debug-tx.md
    └── mvx-token-management.md

Supported Networks

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run npm run build to verify
5. Submit a pull request

License

MIT