MCP Server: NEAR Smart Contract Interaction

An MCP (Model Context Protocol) server that allows Claude to read NEAR smart contract state, call view methods, decode transactions, and understand contract interfaces.

Features

• Contract Metadata: Fetch code hash, storage usage, and detect implemented standards (NEP-141, NEP-171, etc.)
• View Method Calls: Call any read-only method on any NEAR contract
• Transaction Decoding: Decode and explain transaction actions, gas usage, and outcomes
• State Reading: Read raw contract state with optional key prefix filtering
• Interface Explanation: AI-friendly explanation of contract purpose and functions

Installation

npm install @near-mcp/contract-interaction

Or run directly:

npx @near-mcp/contract-interaction

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "near-contract": {
      "command": "npx",
      "args": ["@near-mcp/contract-interaction"]
    }
  }
}

Available Tools

1. get_contract_metadata

Fetches contract metadata including code hash, storage usage, and detected methods/standards.

Input:

{
  "contract_id": "wrap.near",
  "network": "mainnet"
}

Output:

{
  "contract_id": "wrap.near",
  "network": "mainnet",
  "code_hash": "ABC123...",
  "storage_usage_bytes": 12345,
  "storage_usage_near": "0.12345 NEAR",
  "detected_methods": ["ft_transfer", "ft_balance_of", "ft_metadata"],
  "detected_standards": ["NEP-141 (Fungible Token Standard)"]
}

2. call_view_method

Calls a view (read-only) method on any NEAR smart contract.

Input:

{
  "contract_id": "wrap.near",
  "method_name": "ft_balance_of",
  "args": { "account_id": "example.near" },
  "network": "mainnet"
}

Output:

{
  "contract_id": "wrap.near",
  "method": "ft_balance_of",
  "args": { "account_id": "example.near" },
  "result": "1000000000000000000000000",
  "blockHeight": 123456789,
  "blockHash": "ABC...",
  "logs": []
}

3. decode_transaction

Decodes and explains a NEAR transaction, including all actions and their effects.

Input:

{
  "tx_hash": "ABC123...",
  "sender_id": "example.near",
  "network": "mainnet"
}

Output:

{
  "hash": "ABC123...",
  "signerId": "example.near",
  "receiverId": "wrap.near",
  "actions": [
    {
      "type": "FunctionCall",
      "description": "Calls method \"ft_transfer\" with 0.0100 NEAR attached",
      "details": {
        "method_name": "ft_transfer",
        "args_decoded": { "receiver_id": "bob.near", "amount": "1000000" },
        "gas": 30000000000000,
        "deposit": "1"
      }
    }
  ],
  "outcome": {
    "status": "Success",
    "gasUsed": "2.5432 TGas",
    "tokensBurned": "0.000254 NEAR"
  }
}

4. get_contract_state

Reads raw contract state entries, optionally filtered by key prefix.

Input:

{
  "contract_id": "example.near",
  "key_prefix": "",
  "network": "mainnet"
}

Output:

{
  "contract_id": "example.near",
  "network": "mainnet",
  "total_entries": 42,
  "state_entries": [
    {
      "key": "base64...",
      "keyDecoded": "STATE",
      "value": "base64...",
      "valueDecoded": "{\"owner\": \"alice.near\"}"
    }
  ],
  "truncated": false
}

5. explain_contract_interface

Analyzes a contract and provides a human-readable explanation of its purpose and main functions.

Input:

{
  "contract_id": "wrap.near",
  "network": "mainnet"
}

Output:

{
  "contract_id": "wrap.near",
  "network": "mainnet",
  "summary": "Wrapped NEAR (wNEAR) - A fungible token contract implementing the NEP-141 standard...",
  "detected_standards": ["NEP-141 (Fungible Token Standard)", "NEP-145 (Storage Management)"],
  "main_functions": {
    "token_operations": ["ft_transfer", "ft_transfer_call"],
    "queries": ["ft_balance_of", "ft_total_supply", "ft_metadata"],
    "storage": ["storage_deposit", "storage_withdraw"]
  },
  "token_info": {
    "name": "Wrapped NEAR",
    "symbol": "wNEAR",
    "decimals": 24
  },
  "example_usage": [
    "Check token balance: call_view_method(\"wrap.near\", \"ft_balance_of\", {\"account_id\": \"user.near\"})",
    "Get token info: call_view_method(\"wrap.near\", \"ft_metadata\", {})"
  ]
}

Supported Contract Standards

The server automatically detects contracts implementing:

• NEP-141: Fungible Token Standard
• NEP-171: Non-Fungible Token Standard
• NEP-145: Storage Management
• NEP-148: Fungible Token Metadata

Networks

Both mainnet and testnet are supported. Default is mainnet.

{ "network": "testnet" }

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

License

MIT