MultiversX MCP Server

A comprehensive Model Context Protocol (MCP) server implementation for the MultiversX blockchain ecosystem. This server provides AI agents and applications with access to MultiversX SDK-dApp v5 documentation, development resources, and blockchain data querying capabilities.

🚀 Features

📚 Resources (Knowledge Base)

• SDK-dApp v5 Complete Guide (mx://sdk-dapp-guide) - Comprehensive MultiversX SDK-dApp v5 documentation including architecture, installation, configuration, and best practices

🔧 Tools (Executable Functions)

• Query Account (mx-query-account) - Retrieve account information from any MultiversX network
• SDK-DAPP Guide (mx-sdk-dapp-guide) - Fetch the latest SDK-DAPP v5 guide from GitHub with optional section extraction

📦 Installation

Prerequisites

• Node.js (v18 or higher)
• pnpm (recommended) or npm

Quick Setup

# Clone the repository
git clone <repository-url>
cd mx-dev-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

# Test the server (optional)
pnpm start

🔧 Development

# Watch mode for development
npm run watch

# Run in development mode
npm run dev

# Run linting
npm run lint

# Run tests
npm test

# Clean build artifacts
npm run clean

⚙️ Configuration

Environment Variables

• LOG_LEVEL - Set logging level (DEBUG, INFO, WARN, ERROR)
• MULTIVERSX_NETWORK - Default network (mainnet, testnet, devnet)

Network Support

The server supports all MultiversX networks:

• Mainnet - Production network
• Testnet - Testing network
• Devnet - Development network

🏗️ Project Structure

src/
├── index.ts              # Main entry point
├── resources/            # MCP resources (documentation)
│   ├── index.ts              # Resource handler setup
│   └── sdk-dapp-guide.ts     # Complete SDK-dApp guide
├── tools/               # MCP tools (executable functions)
│   ├── index.ts             # Tool handler setup
│   ├── query-account.ts     # Account querying tool
│   └── sdk-dapp-guide.ts    # SDK-dApp guide tool
├── prompts/             # MCP prompts (templates) - Currently empty
│   └── index.ts             # Prompt handler setup
├── utils/               # Utilities
│   ├── constants.ts         # Constants and configurations
│   └── logger.ts            # Logging utility

🔌 Client Integration

Cursor IDE Integration

#### Step 1: Clone and Setup

git clone <repository-url>
cd mx-dev-mcp
pnpm install && pnpm build

#### Step 2: Configure Cursor MCP Settings

Add to Cursor Settings → Features → Model Context Protocol:

{
  "mcpServers": {
    "mvx-dev-mcp": {
      "name": "MultiversX SDK development MCP Server",
      "command": "node",
      "args": ["<absolute-path-to-repo>/mx-dev-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Important: Replace <absolute-path-to-repo> with the actual absolute path.

#### Step 3: Alternative Configuration (npm link)

# In the mx-dev-mcp directory
npm link

# Then in Cursor MCP settings:
{
  "name": "MultiversX MCP Server",
  "command": "mx-dev-mcp"
}

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "mvx-dev-mcp": {
      "name": "MultiversX SDK development MCP Server",
      "command": "node",
      "args": ["<absolute-path-to-repo>/mx-dev-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

📚 Resources Documentation

SDK-dApp v5 Complete Guide (mx://sdk-dapp-guide)

Comprehensive guide covering MultiversX SDK-dApp v5 architecture, installation, configuration, provider interactions, data access patterns, transaction management, network configuration, account management, UI components, and debugging strategies.

🔧 Tools Documentation

Query Account Tool (mx-query-account)

Query MultiversX account information including balance, nonce, transactions, guardian status, assets, and more for any network (mainnet, testnet, devnet).

Parameters:

• address (required): MultiversX account address (erd1... format)
• network: MAINNET, TESTNET, or DEVNET (default: MAINNET)
• withGuardianInfo: Include guardian information in the response (default: false)
• withTxCount: Include transaction count in the response (default: false)
• withScrCount: Include smart contract results count in the response (default: false)
• withTimestamp: Include timestamp of last activity in the response (default: false)
• withAssets: Include assets (tokens/NFTs) in the response (default: false)
• timestamp: Retrieve account state from a specific timestamp

Response Format:

• Address and balance information
• Transaction counts and activity
• Guardian status (if requested)
• Smart contract details (if applicable)
• Asset information (if requested)
• Verification status and metadata

Usage Examples:

Query the MultiversX account erd1qga7ze0l03chfgru0a32wxqf2226nzrxnyhzer9lmudqhjgy7ycqjjyknz

Get balance for address erd1qga7ze0l03chfgru0a32wxqf2226nzrxnyhzer9lmudqhjgy7ycqjjyknz on testnet

Show detailed account info with transaction count and guardian status for erd1qga7ze0l03chfgru0a32wxqf2226nzrxnyhzer9lmudqhjgy7ycqjjyknz

SDK-DAPP Guide Tool (mx-sdk-dapp-guide)

Fetch the MultiversX SDK-DAPP v5 guide from the official GitHub repository, including setup and usage for React, TypeScript, JavaScript, Angular, login/logout, signing, sending, tracking transactions, signing messages, and creating custom providers. Optionally, provide a section name to extract a specific section.

Parameters:

• section (optional): The section name to extract from the guide (e.g., Installation, Configuration, Transactions, etc.)

Response Format:

• Markdown content of the full guide or the requested section

Usage Examples:

#### Basic Usage - Fetch Complete Guide

Fetch the complete MultiversX SDK-DAPP v5 guide

#### Setup SDK-dApp

Get the SDK-dApp installation and setup instructions

_Use section: "Installation"_

#### Login and Logout with SDK-dApp

Show me how to implement login and logout functionality with SDK-dApp

_Use section: "Login" or "Logout" or "Authentication"_

#### Sign/Send/Track Transactions

Get information about signing, sending, and tracking transactions with SDK-dApp

_Use section: "Transactions" or "Signing Transactions"_

#### Get Account Information

Show me how to get account information using SDK-dApp

_Use section: "Account" or "Getting account data"_

#### Sign Messages

Get information about signing messages with SDK-dApp

_Use section: "Signing Messages" or "Message Signing"_

#### Configuration and Setup

Get the SDK-dApp configuration and initialization guide

_Use section: "Configuration" or "Setup"_

#### Provider Management

Show me how to work with different wallet providers in SDK-dApp

_Use section: "Providers" or "Wallet Providers"_

#### UI Components

Get information about SDK-dApp UI components

_Use section: "UI Components" or "Components"_

#### Advanced Usage Examples

1. Fetch specific sections:

   Get only the "Installation" section from the SDK-DAPP guide

1. Transaction workflow:

   Show me the complete transaction workflow from signing to tracking

1. Provider integration:

   How do I integrate different wallet providers with SDK-dApp?

1. Account management:

   Get the account management section from the SDK-DAPP guide

1. Network configuration:

   Show me how to configure networks in SDK-dApp

🛠️ Tool Usage Examples

Query Account Tool

• Query a mainnet account:

  Query the MultiversX account erd1qga7ze0l03chfgru0a32wxqf2226nzrxnyhzer9lmudqhjgy7ycqjjyknz

• Query an account on testnet:

  Get balance for address erd1qga7ze0l03chfgru0a32wxqf2226nzrxnyhzer9lmudqhjgy7ycqjjyknz on testnet

• Show detailed info with transaction count and guardian status:

  Show detailed account info with transaction count and guardian status for erd1qga7ze0l03chfgru0a32wxqf2226nzrxnyhzer9lmudqhjgy7ycqjjyknz

SDK-DAPP Guide Tool

• Fetch the entire guide:

  Fetch the complete MultiversX SDK-DAPP v5 guide

• Fetch a specific section:

  Get only the "Installation" section from the SDK-DAPP guide

• Get setup instructions:

  Show me how to set up SDK-dApp in my project

• Get authentication guide:

  How do I implement login and logout with SDK-dApp?

• Get transaction guide:

  Show me how to sign and send transactions with SDK-dApp

🔧 Troubleshooting

Common Issues

#### 1. MCP Server Not Connecting

Problem: Cursor shows "MCP server failed to start" Solutions:

• Ensure absolute path is correct in configuration
• Verify project is built: pnpm build
• Check Node.js installation and accessibility
• Restart Cursor after configuration changes

#### 2. Account Query Failures

Problem: "Account not found" or API errors Solutions:

• Verify address format (must start with "erd1")
• Check network connectivity
• Try with known valid address: erd1qga7ze0l03chfgru0a32wxqf2226nzrxnyhzer9lmudqhjgy7ycqjjyknz
• Ensure correct network selection

#### 3. Build Errors

Problem: TypeScript compilation errors Solutions:

• Ensure Node.js version 18+
• Clean install: rm -rf node_modules && pnpm install
• Check TypeScript errors: pnpm tsc --noEmit

#### 4. SDK-DAPP Guide Fetch Issues

Problem: Guide not loading or sections not found Solutions:

• Check internet connectivity
• Verify section names are correct (case-insensitive matching)
• Try fetching the complete guide first
• Check GitHub repository accessibility

Debug Mode

Enable debug logging:

{
  "env": {
    "LOG_LEVEL": "DEBUG"
  }
}

Getting Help

If you encounter issues:

1. Check troubleshooting section
2. Verify setup against installation instructions
3. Test server independently: pnpm start
4. Check MCP server logs in client settings
5. Review console output for error details

🏆 Best Practices

Security

• Always validate addresses before querying
• Use appropriate network for development/production
• Follow SDK-dApp security guidelines
• Implement proper error handling

Performance

• Cache frequently accessed documentation
• Use section-specific queries when possible
• Monitor API rate limits
• Optimize query parameters

Development

• Use development networks for testing
• Follow TypeScript best practices
• Implement comprehensive error handling
• Document custom implementations

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details

🔗 Links

• MultiversX Official Site
• Model Context Protocol
• MultiversX SDK-dApp
• Template dApp
• MultiversX Documentation