README.md

metadata

title: URLScan.io MCP Server
emoji: 🔍
colorFrom: blue
colorTo: red
sdk: docker
sdk_version: 5.35.0
python_version: 3.13.0
app_file: app.py
pinned: false
license: apache-2.0
tags:
  - MCP

urlscan-mcp-server

Expose urlscan.io API as MCP tools using FastMCP.

Features

• Search for past scans (search)
• Retrieve scan results by UUID (get_result)
• Submit a new URL for scanning (submit_url)
• Detailed tool documentation and usage examples
• Global prompt to guide optimal tool usage

Requirements

• Docker
• A valid urlscan.io API key (set as environment variable URLSCAN_API_KEY)

Usage

1. Build the Docker image

docker build -t urlscan-mcp-server .

2. Run the server

docker run -e URLSCAN_API_KEY=your_urlscan_api_key -p 8000:8000 urlscan-mcp-server

• Replace your_urlscan_api_key with your actual urlscan.io API key.
• The server will be available on http://localhost:8000 (or the port you choose).

3. API/Tool Usage

• The MCP server exposes three tools: search, get_result, and submit_url.
• Refer to the detailed docstrings in app.py for usage and examples.
• The server provides a global prompt to guide LLMs or users for optimal usage (search first, scan only if needed).

Development

Install dependencies locally (optional)

pip install -r requirements.txt

Run locally (optional)

export URLSCAN_API_KEY=your_urlscan_api_key
python app.py

Notes

• Gradio SDK is not used. All interaction is via MCP protocol (HTTP, OpenAPI, or compatible LLM clients).
• For more information on urlscan.io API, see: https://urlscan.io/docs/api/