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_*)

| Tool | Description | Wallet | |------|-------------|:------:| | mvx_sc_query | Query view/endpoint with ABI encoding/decoding | No | | mvx_sc_storage | Read a storage key (mapper name or 0x-prefixed hex) | No | | mvx_sc_storage_keys | List all storage keys | No | | mvx_sc_abi | Inspect contract ABI (endpoints, views, types) | No | | mvx_sc_decode | Decode hex data using ABI types | No | | mvx_sc_simulate | Simulate a SC call (gas, results, errors) | No | | mvx_sc_estimate_gas | Estimate gas cost for a SC call | No | | mvx_sc_call | Call a SC endpoint (transaction) | Yes | | mvx_sc_deploy | Deploy a new smart contract | Yes | | mvx_sc_upgrade | Upgrade an existing smart contract | Yes | | mvx_sc_verify | Submit contract verification to explorer | Yes | | mvx_sc_verify_status | Check verification task progress | No |

Development Tools (mvx_sc_*)

| Tool | Description | Wallet | |------|-------------|:------:| | mvx_sc_build | Build WASM via sc-meta | No | | mvx_sc_test | Run cargo test / sc-meta test | No | | mvx_sc_new | Create new SC from template | No | | mvx_sc_proxy | Generate typed proxy bindings | No | | mvx_sc_compare | Compare local WASM with deployed bytecode | No | | mvx_sc_reproducible_build | Docker-based deterministic build | No |

General Blockchain Tools (mvx_*)

| Tool | Description | Wallet | |------|-------------|:------:| | mvx_account | Account/contract info (balance, owner, properties) | No | | mvx_search | Search contracts by name on the network | No | | mvx_transfer | Send EGLD or ESDT tokens | Yes | | mvx_tx_result | Get transaction results with decoded outputs | No | | mvx_token_info | ESDT/NFT token details (decimals, supply, roles) | No | | mvx_network_config | Chain config, epoch, gas parameters, stats | No | | mvx_convert | Convert between bech32, hex, decimal, string, base64 | No | | mvx_format_amount | Denominate/nominate token amounts (raw/human) | No | | mvx_sign_message | Sign a message with PEM wallet | Yes | | mvx_verify_sig | Verify a message signature | No | | mvx_native_auth_decode | Decode a native auth token | No | | mvx_native_auth_generate | Generate a native auth token | Yes | | mvx_wallet_new | Create a new wallet (PEM or JSON) | No | | mvx_wallet_info | Get address from a PEM file | No |

Token Management (mvx_token_*)

| Tool | Description | Wallet | |------|-------------|:------:| | mvx_token_issue_fungible | Issue a new fungible ESDT token | Yes | | mvx_token_issue_nft | Issue (register) a new NFT collection | Yes | | mvx_token_issue_sft | Issue (register) a new SFT collection | Yes | | mvx_token_issue_meta_esdt | Issue (register) a new Meta-ESDT collection | Yes | | mvx_token_create_nft | Create a new NFT/SFT/Meta-ESDT nonce under a collection | Yes |

Batch Transfers

| Tool | Description | Wallet | |------|-------------|:------:| | mvx_batch_transfer_egld | Send EGLD to multiple recipients in one transaction | Yes | | mvx_batch_transfer_tokens | Send ESDT tokens to multiple recipients in one transaction | Yes |

Relayed Transactions

| Tool | Description | Wallet | |------|-------------|:------:| | mvx_relayed_transaction | Send a relayed v3 transaction (pay gas on behalf of another account) | Yes |

Setup

| Tool | Description | Wallet | |------|-------------|:------:| | mvx_setup | Configure permissions (auto-approve read-only tools) | No |

AI Workflows (MCP Prompts)

Built-in guided workflows that orchestrate the tools above:

| Prompt | Description | |--------|-------------| | mvx | Main orchestrator — shows all capabilities, routes to the right workflow | | mvx_audit_onchain | Audit a deployed contract using on-chain data (queries views, reads storage, checks ABI) | | mvx_audit_source | Audit source code with patterns A-M, severity calibration, and quality gates | | mvx_test_contract | Automated testing — query all views, read storage, simulate calls, generate report | | mvx_deploy_flow | Guided deployment: build, deploy, verify, test | | mvx_upgrade_flow | Guided upgrade with pre/post verification and mainnet safety confirmation | | mvx_debug_tx | Debug a transaction — decode results, events, identify failure reason | | mvx_token_management | Inspect and manage ESDT tokens — query info, check roles, troubleshoot |

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

| Variable | Default | Description | |----------|---------|-------------| | MULTIVERSX_NETWORK | mainnet | Default network (mainnet, testnet, devnet) | | MULTIVERSX_API_URL | (auto) | Custom API URL (overrides network default) | | MULTIVERSX_GATEWAY_URL | (auto) | Custom gateway URL | | MULTIVERSX_WALLET_PEM | (none) | Path to PEM wallet (for write operations) | | MULTIVERSX_DEFAULT_GAS_LIMIT | 50000000 | Default gas limit for SC calls |

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

| Network | API | Gateway | |---------|-----|---------| | Mainnet | https://api.multiversx.com | https://gateway.multiversx.com | | Testnet | https://testnet-api.multiversx.com | https://testnet-gateway.multiversx.com | | Devnet | https://devnet-api.multiversx.com | https://devnet-gateway.multiversx.com |

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