BICScan MCP Server: Blockchain Address Risk Scoring

Overview

BICScan MCP Server integrates the BICScan risk-scanning API into a Model Context Protocol (MCP) server that can be run locally or inside Docker. It provides on-demand blockchain address risk scoring, asset holdings enumeration, and domain/dApp assessments so developer tools, chat assistants, and automated workflows can quickly surface on-chain risk signals without embedding the remote API directly.

This server is most useful for developers building AML/Compliance pipelines, security dashboards, DeFi monitoring, or any application that needs quick, programmatic insights on addresses and smart-contract endpoints. The MCP server acts as a small adapter around the BICScan API with built-in configuration for running in Claude Desktop (MCP) environments or as a standalone container.

Features

• Risk scoring (0–100): aggregated risk scores for addresses, domains, and dApp URLs (100 = high risk).
• Asset inventory: list of native balances, ERC-20/ERC-721 token holdings and summarized fiat values across supported chains.
• Domain & dApp checks: reputation and metadata for domains and decentralized application URLs.
• Real-time queries: forwards requests to BICScan to fetch up-to-date results.
• Simple integration: runs with uv / uvx (for Claude Desktop) or Docker.
• Configurable via environment variable BICSCAN_API_KEY.
• Robust logging and error handling for predictable responses.

Installation / Configuration

Prerequisites

• Python 3.10+
• uv 0.6.x (for uv/uvx runs) or Docker (for container runs)
• git

Clone the repository:

git clone https://github.com/ahnlabio/bicscan-mcp
cd bicscan-mcp

Get a free BICScan API key:

1. Register at https://bicscan.io
2. In your profile create an application and copy the API key.

Environment variable

export BICSCAN_API_KEY="YOUR_BICSCAN_API_KEY_HERE"

Run with uv (local, recommended for development)

uv --directory /path/to/bicscan-mcp run bicscan-mcp

Run with Docker

# build
make

# run (replace API key)
docker run --rm -it --env BICSCAN_API_KEY="YOUR_BICSCAN_API_KEY_HERE" bicscan-mcp

Run with uvx (pull and run from Git)

uvx --from git+https://github.com/ahnlabio/bicscan-mcp bicscan-mcp

Claude Desktop MCP configuration examples Add a bicscan entry to your claude_desktop_config.json (uv example):

{
  "mcpServers": {
    "bicscan": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/you/repos/bicscan-mcp",
        "run",
        "bicscan-mcp"
      ],
      "env": {
        "BICSCAN_API_KEY": "YOUR_BICSCAN_API_KEY_HERE"
      }
    }
  }
}

Docker entry:

{
  "mcpServers": {
    "bicscan": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env", "BICSCAN_API_KEY=YOUR_BICSCAN_API_KEY_HERE",
        "bicscan-mcp"
      ]
    }
  }
}

uvx entry:

{
  "mcpServers": {
    "bicscan": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/ahnlabio/bicscan-mcp",
        "bicscan-mcp"
      ],
      "env": {
        "BICSCAN_API_KEY": "YOUR_BICSCAN_API_KEY_HERE"
      }
    }
  }
}

Table: run modes at a glance

Available Resources

• GitHub repository: https://github.com/ahnlabio/bicscan-mcp
• BICScan portal (get API key and docs): https://bicscan.io
• Example integration: claude_desktop_config.json snippets (see above)

The MCP server itself exposes the scanning functionality to the MCP consumer (e.g., Claude Desktop) and forwards requests to BICScan. Use the repository to inspect implementation, logging, and response mapping.

Example output (representative)

A typical scan response returned by the server might look like:

{
  "address": "0xAbC123...def",
  "risk_score": 78,
  "categories": ["fraud", "phishing"],
  "assets": [
    {"token": "ETH", "balance": "1.234", "usd_value": 2500},
    {"token": "USDC", "balance": "1000", "usd_value": 1000}
  ],
  "last_scanned": "2026-04-01T12:34:56Z",
  "notes": "Associated with phishing site example[.]com"
}

Fields may include additional metadata such as chain name, contract labels, and links to the BICScan report.

Use Cases

• AML / Compliance: screen incoming wallet addresses against risk scores before onboarding or accepting deposits.
• Automated monitoring: set up cron jobs that call the MCP server to re-scan high-value addresses and trigger alerts on score changes.
• KYC investigations: enrich off-chain identity data with on-chain asset snapshots and domain/dApp reputations.
• Smart-contract audits / DeFi integrations: vet counterparty addresses and dApp endpoints prior to integration or liquidity provisioning.

Concrete example (address screening)

1. Run the