💫 MCP NEAR Agents

Package: @iqai/mcp-near
Purpose: NEAR Protocol blockchain integration with AI-driven event processing

Key Features

✅ Execute contract methods and transactions on NEAR blockchain
✅ Listen to and respond to contract events with AI processing
✅ View contract data and account information
✅ Handle custom logic through intelligent event listeners
✅ Compatible with any MCP client

🔧 Available Tools

`watch_near_event`

Start watching for specific events on a NEAR contract:

{
  eventName: "run_agent",           // Event to watch for
  contractId: "contract.testnet",   // Contract to monitor
  responseMethodName: "agent_response", // Method to call with AI response
  cronExpression: "*/10 * * * * *"  // Optional: polling frequency
}

`stop_watching_near_event`

Stop watching for specific events:

{
  contractId: "contract.testnet",
  eventName: "run_agent"
}

`list_watched_near_events`

List all currently watched events and statistics:

{
  includeStats: true; // Optional: include performance statistics
}

🤖 AI-Driven Event Processing Workflow

The server enables an “AI in the loop” workflow:

🔗 Smart contract transaction triggers an event and pauses execution
🤖 MCP server detects the event and requests AI processing from the client
🧠 AI client processes the event data and provides intelligent response
↩️ Server sends AI response back to blockchain via transaction
✅ Original smart contract resumes with the AI-provided data

🌜 Event Processing Flow

When a blockchain event is detected:

📡 Event Detection: Server monitors blockchain for specified events
🤖 AI Request: Server requests sampling from MCP client with event data
🧠 AI Processing: Client processes event and returns intelligent response
📤 Blockchain Response: Server sends AI response back to contract
📊 Statistics: Performance metrics are tracked and available

Environment Variables

Variable	Description
`ACCOUNT_ID`	Your NEAR account ID for authentication
`ACCOUNT_KEY`	Private key for your NEAR account (ed25519: or secp256k1: format)
`NEAR_NETWORK_ID`	NEAR network (“mainnet”, “testnet”, “betanet”) - defaults to “mainnet”
`NEAR_NODE_URL`	Custom NEAR RPC endpoint (optional)
`NEAR_GAS_LIMIT`	Gas limit for transactions (optional)

Configuration Example

{
  "mcpServers": {
    "near-server": {
      "command": "pnpm",
      "args": ["dlx", "@iqai/mcp-near"],
      "env": {
        "ACCOUNT_ID": "your-account.testnet",
        "ACCOUNT_KEY": "ed25519:your_private_key_here",
        "NEAR_NETWORK_ID": "testnet"
      }
    }
  }
}

🎯 Usage Examples

Start the MCP server with your client

Watch for events using the MCP tool:

Use watch_near_event with:
- eventName: "price_request"
- contractId: "oracle.testnet"
- responseMethodName: "price_response"

AI processes events automatically when they occur on the blockchain
Monitor with list_watched_near_events to see status and statistics

📊 Response Format

The server provides structured responses:

✔ Success/failure status with detailed messages
🔗 Subscription IDs for tracking active watchers
📈 Performance statistics (success rates, processing times)
🎯 Event details (contract, event type, timestamps)
💡 Helpful guidance and troubleshooting tips

❌ Error Handling

The server handles common NEAR-related errors:

🚨 Invalid contract calls or method names
💸 Insufficient account balance for transactions
🔑 Authentication issues with account credentials
🌐 Network connectivity problems with NEAR RPC
🚫 Contract execution errors returned by smart contracts
⏱️ Timeout handling for long-running operations