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, projectPath)
→ mvx_sc_verify_status(taskId)
→ mvx_test_contract prompt for automated testing

Rust toolchains and source verification

mvx_sc_reproducible_build includes the repository's rust-toolchain.toml or rust-toolchain files in every generated .source.json, including nested contract overrides. It preserves their exact contents; it does not hard-code a Rust version. When mxpy is unavailable it uses the official Docker builder directly (Docker must be installed and running).

For an existing package or a downloaded release, pass projectPath to mvx_sc_verify pointing to the exact repository checkout used for that build. The tool adds missing toolchain files to the request before hashing/signing and leaves the input JSON unchanged. Conflicting toolchains stop submission. A package without a toolchain requires projectPath; if that repository has none, the result explicitly reports use of the Docker default.

{
  "address": "erd1...",
  "packagedSrc": "/path/to/router-0.0.0.source.json",
  "projectPath": "/path/to/mx-exchange-sc-at-release-tag",
  "dockerImage": "multiversx/sdk-rust-contract-builder:v10.0.0",
  "network": "mainnet"
}

The Docker image's buildMetadata.versionRust can describe its preinstalled compiler, even when Rustup selects another compiler through the project's configuration. The MCP preserves that builder metadata and reports included toolchain files separately. Successful local compilation is not server verification: check mvx_sc_verify_status and Explorer publication afterward.

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