agentis-dev/NFT-Scanner-MCP

NFT Scanner MCP Server

A comprehensive Model Context Protocol (MCP) server that provides real-time blockchain data for NFTs across multiple networks. Built for AI assistants to access live NFT market data, ownership information, and transaction history.

🚀 Features

Real-Time NFT Data

• Collection Analytics: Floor prices, volume, market cap, owner counts
• Live Metadata: Token details, attributes, ownership tracking
• Transaction History: Transfers, sales, marketplace activity
• Multi-chain Support: Ethereum, Polygon, Arbitrum, Optimism

Market Intelligence

• Floor Price Tracking: Real-time prices across OpenSea, LooksRare, Blur
• Sales History: Detailed transaction data with pricing and timestamps
• Collection Search: Find NFT projects by name or description
• Wallet Analysis: Complete NFT portfolio for any address

Data Sources

• Alchemy NFT API - Primary blockchain data
• OpenSea API - Marketplace statistics and events
• NFTScan API - Additional data validation

📊 Available Tools

🛠️ Installation & Setup

Prerequisites

• Node.js 18+
• npm or yarn
• API keys (see configuration below)

Quick Start

1. Clone and Install

git clone <repository-url>
cd nft-scanner-mcp
npm install

2. Configure API Keys

cp env.example .env
# Edit .env with your API keys

3. Run the Server

npm start

4. Test with Demo

npm test

🔑 API Configuration

Required: Alchemy API Key

# Get free API key at: https://dashboard.alchemy.com/
ALCHEMY_API_KEY=your_alchemy_api_key_here

Optional: Enhanced Data Sources

# OpenSea API (recommended for market data)
OPENSEA_API_KEY=your_opensea_api_key_here

# NFTScan API (additional validation)
NFTSCAN_API_KEY=your_nftscan_api_key_here

Getting API Keys

1. Alchemy (Required)

   • Sign up for free account
   • Create new app
   • Copy API key from dashboard

2. OpenSea (Recommended)

   • Apply for API access
   • Enhanced marketplace data

3. NFTScan (Optional)

   • Additional data source for validation

💡 Usage Examples

Get Collection Details

{
  "name": "getNFTCollectionDetails",
  "arguments": {
    "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
    "chain": "ethereum"
  }
}

Response:

{
  "collectionDetails": {
    "name": "Bored Ape Yacht Club",
    "totalSupply": "10000",
    "marketStats": {
      "floorPrice": 15.75,
      "totalVolume": 682544.23,
      "numOwners": 5420,
      "sevenDayVolume": 1205.67
    }
  }
}

Get NFT Metadata

{
  "name": "getNFTMetadata", 
  "arguments": {
    "contractAddress": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D",
    "tokenId": "1000"
  }
}

Check Wallet NFTs

{
  "name": "getWalletNFTs",
  "arguments": {
    "walletAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "limit": 50
  }
}

Search Collections

{
  "name": "searchNFTCollections",
  "arguments": {
    "query": "Azuki",
    "limit": 10
  }
}

🌐 Supported Networks

🔍 Data Structure

Collection Details Response

{
  timestamp: string;
  contractAddress: string;
  chain: string;
  collectionDetails: {
    name: string;
    description: string;
    totalSupply: number;
    symbol: string;
    contractType: string;
    verified: boolean;
    marketStats: {
      floorPrice: number;
      totalVolume: number;
      totalSales: number;
      averagePrice: number;
      numOwners: number;
      oneDayVolume: number;
      sevenDayVolume: number;
    };
    social: {
      website: string;
      discord: string;
      twitter: string;
    };
  };
}

NFT Metadata Response

{
  timestamp: string;
  contractAddress: string;
  tokenId: string;
  metadata: {
    name: string;
    description: string;
    image: string;
    attributes: Array<{
      trait_type: string;
      value: string;
    }>;
    owner: string;
    tokenType: string;
  };
}

⚡ Performance & Rate Limits

• Built-in Rate Limiting: 1 request per second
• Automatic Retries: Up to 3 retries with exponential backoff
• Request Caching: Smart caching to reduce API calls
• Error Handling: Graceful degradation when APIs are unavailable

🎯 Real-World Applications

For AI Assistants

• Market Analysis: "What's the current floor price of BAYC?"
• Portfolio Tracking: "Show me all NFTs in wallet 0x..."
• Collection Research: "Find information about Azuki collection"
• Transaction Monitoring: "Get recent sales for CryptoPunks"

For Developers

• NFT Portfolio Apps: Real-time wallet tracking
• Market Dashboards: Live collection statistics
• Trading Bots: Floor price monitoring
• Analytics Platforms: Historical transaction data

🔧 Development

Project Structure

nft-scanner-mcp/
├── nft-scanner-mcp-server.js    # Main MCP server
├── demo-nft-scanner-mcp.js      # Demo/testing script
├── package.json                 # Dependencies
├── env.example                  # Environment template
└── README.md                    # This file

Running Tests

# Run demo with sample data
npm test

# Start server in development mode
npm run dev

Adding New Features

The server is designed to be extensible. To add new NFT data sources:

1. Add new tool definition in setupToolHandlers()
2. Implement the corresponding method
3. Update rate limiting and error handling
4. Add example usage to demo script

🛡️ Error Handling

The server includes comprehensive error handling:

• API Failures: Automatic fallback to alternative data sources
• Rate Limiting: Exponential backoff with retry logic
• Invalid Addresses: Validation and clear error messages
• Network Issues: Graceful degradation and timeout handling

📈 Monitoring

All requests include:

• Timestamps: ISO 8601 format
• Data Sources: Clear attribution of data origin
• Request IDs: For debugging and tracking
• Performance Metrics: Response times and success rates

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

📄 License

This project is licensed under the MIT License - see the file for details.

🔗 Related Projects

• Real-time Crypto MCP - Cryptocurrency data
• Model Context Protocol - Official MCP documentation
• Alchemy NFT API - Primary data source

📞 Support

• Issues: GitHub Issues
• Documentation: MCP Docs
• Community: Discord | Twitter

Built with ❤️ for the Web3 community