🔗 NEAR Intent Swaps MCP Server

📖 Overview

The NEAR Intent Swaps MCP Server enables AI agents to perform cross-chain token swaps through NEAR's intent-based architecture using the Defuse Protocol one-click SDK. This server provides a comprehensive 5-step flow for discovering tokens, getting quotes, executing swaps, and tracking their status.

By implementing the Model Context Protocol (MCP), this server allows Large Language Models (LLMs) to facilitate cross-chain swaps seamlessly, bridging the gap between AI assistants and decentralized cross-chain infrastructure.

Related MCP server: sui-trader-mcp

✨ Features

• Token Discovery: Discover available tokens across multiple blockchains supported by the Defuse Protocol.

• Simple Quotes: Get basic swap quotes without requiring addresses - perfect for rate checking.

• Full Quotes: Get complete quotes with deposit addresses for executing swaps.

• Swap Execution: Submit deposit transaction hashes to execute cross-chain swaps.

• Status Tracking: Monitor swap progress and completion status in real-time.

📦 Installation

🚀 Using npx (Recommended)

To use this server without installing it globally:

npx @iqai/mcp-near-intent-swaps

🔧 Build from Source

git clone https://github.com/IQAIcom/mcp-near-intent-swaps.git
cd mcp-near-intent-swaps
pnpm install
pnpm run build

⚡ Running with an MCP Client

Add the following configuration to your MCP client settings (e.g., claude_desktop_config.json).

📋 Minimal Configuration

{
  "mcpServers": {
    "near-intent-swaps": {
      "command": "npx",
      "args": ["-y", "@iqai/mcp-near-intent-swaps"],
      "env": {
        "NEAR_SWAP_JWT_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

⚙️ Advanced Configuration (Local Build)

{
  "mcpServers": {
    "near-intent-swaps": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-near-intent-swaps/dist/index.js"],
      "env": {
        "NEAR_SWAP_JWT_TOKEN": "your-jwt-token-here",
        "NEAR_SWAP_API_URL": "https://1click.chaindefuser.com"
      }
    }
  }
}

🔐 Configuration (Environment Variables)

💡 Usage Examples

🔍 Token Discovery

• "What tokens are available for cross-chain swaps on NEAR?"

• "Show me all supported tokens in the Defuse Protocol."

• "List available tokens I can swap from Arbitrum to Solana."

📊 Getting Quotes

• "What's the rate to swap 100 USDC from Arbitrum to SOL?"

• "Get me a quote for swapping ETH to USDC on NEAR."

• "How much SOL would I get for 1000 USDC?"

💱 Executing Swaps

• "I want to swap 500 USDC from Arbitrum to Solana."

• "Help me execute a cross-chain swap with this deposit address."

• "I've sent the funds to the deposit address, here's my transaction hash."

📈 Tracking Status

• "Check the status of my swap with deposit address 0xabc..."

• "Is my cross-chain swap complete?"

• "What's the current state of my pending swap?"

🛠️ MCP Tools

CHECK_NEAR_SWAP_STATUS

[STEP 5] Check the current execution status of a NEAR intent swap. Returns the swap state (PENDING_DEPOSIT, PROCESSING, SUCCESS, REFUNDED, FAILED, etc.) along with detailed transaction information. Use this to monitor swap progress after initiating the swap, and continue polling until the swap is complete.

EXECUTE_NEAR_SWAP

[STEP 4] Submit a deposit transaction hash to initiate the swap after sending funds to the deposit address. This notifies the 1Click service that funds have been sent and triggers the swap execution process. Use this after users have sent their funds to the deposit address from the full quote response.

GET_NEAR_SWAP_FULL_QUOTE

[STEP 2] Get a full quote with deposit address for a NEAR intent swap. This requires recipient and refund addresses and returns a unique deposit address where users can send their funds to initiate the swap. Use this when users are ready to proceed with the swap after checking the simple quote. NOTE: If users provide simple token names (e.g., 'ETH', 'USDC'), first use GET_NEAR_SWAP_TOKENS to discover the exact token IDs required for this API.

GET_NEAR_SWAP_SIMPLE_QUOTE

[STEP 1] Get a simple quote for a NEAR intent swap between different chains and assets. This is a dry run that doesn't require any addresses - perfect for users who want to check swap rates and fees before committing to a swap. Use this when users want to explore swap options without providing recipient addresses. NOTE: If users provide simple token names (e.g., 'ETH', 'USDC'), first use GET_NEAR_SWAP_TOKENS to discover the exact token IDs required for this API.

GET_NEAR_SWAP_TOKENS

[DISCOVERY] Get a list of tokens currently supported by the 1Click API for NEAR Intents. Returns token metadata including blockchain, contract address, current USD price, symbol, decimals, and price update timestamp. Use this to help users discover available tokens before requesting quotes.

No parameters

👨‍💻 Development

🏗️ Build Project

pnpm run build

👁️ Development Mode (Watch)

pnpm run watch

✅ Linting & Formatting

pnpm run lint
pnpm run format

📁 Project Structure

• src/tools/: Individual tool definitions

• src/services/: API client and business logic

• src/lib/: Shared utilities

• src/index.ts: Server entry point

📚 Resources

• Defuse Protocol one-click SDK

• Model Context Protocol (MCP)

• NEAR Protocol

⚠️ Disclaimer

This project interacts with cross-chain swap infrastructure. Users should exercise caution and verify all transaction details before executing swaps. Cross-chain transactions involve multiple blockchains and carry inherent risks.

📄 License

MIT