@ayazdata/trace-mcp

MCP server for Trace — AI-powered malware analysis platform.
Connects Claude Code, Codex CLI, and Gemini CLI directly to a Trace instance.

Live instance: https://trace.akpinar.dev
npm: @ayazdata/trace-mcp

Quick Install

Claude Code

claude mcp add trace -e TRACE_URL=https://trace.akpinar.dev -- npx -y @ayazdata/trace-mcp

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.trace]
command = "npx"
args = ["-y", "@ayazdata/trace-mcp"]
startup_timeout_sec = 15

[mcp_servers.trace.env]
TRACE_URL = "https://trace.akpinar.dev"
TRACE_TOKEN = ""

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "trace": {
      "command": "npx",
      "args": ["-y", "@ayazdata/trace-mcp"],
      "env": {
        "TRACE_URL": "https://trace.akpinar.dev",
        "TRACE_TOKEN": ""
      }
    }
  }
}

Project-level (any tool that supports .mcp.json)

A .mcp.json is included at the repo root — tools that support project-level MCP config will pick it up automatically when you open the project.

Self-hosted

If you run your own Trace instance, replace the URL:

claude mcp add trace -e TRACE_URL=http://localhost:8090 -- npx -y @ayazdata/trace-mcp

For authenticated endpoints, generate a JWT token from Trace settings and pass it:

claude mcp add trace \
  -e TRACE_URL=https://your-instance.com \
  -e TRACE_TOKEN=your_jwt_token \
  -- npx -y @ayazdata/trace-mcp

Available Tools

| Tool | What it does | |------|-------------| | trace_upload_file | Upload a local file for malware analysis. Returns analysis_id. | | trace_get_analysis | Full results for an analysis — risk score, YARA hits, MITRE techniques, IOCs, AI summary. | | trace_list_analyses | List recent analyses. Filter by risk_level or status. | | trace_get_iocs | Extract IOCs (IPs, domains, hashes, URLs, registry keys) from an analysis. | | trace_get_sigma_matches | Sigma detection rules that triggered on a sample. | | trace_get_ai_summary | AI-generated threat narrative for an analysis. | | trace_lookup_hash | Threat intel lookup for a SHA256 hash (VirusTotal + internal DB). | | trace_dashboard_stats | Platform-wide stats: total analyses, risk distribution, detection rates. | | trace_get_mitre | Top MITRE ATT&CK techniques observed across all analyses. | | trace_get_process_tree | Process execution tree from dynamic/sandbox analysis. |

Telegram Bot — @Ayaz_Trace_Bot

Trace also ships a Telegram bot for on-the-go analysis.

Start: Search @Ayaz_Trace_Bot on Telegram or open t.me/Ayaz_Trace_Bot

Commands

| Command | Description | |---------|-------------| | /start | Welcome message and usage guide | | /help | Same as /start | | /set_detail short | Receive compact analysis reports | | /set_detail detailed | Receive full analysis reports (default) |

Usage

1. Send any file as a Document (not compressed) — the bot queues it for analysis.
2. When analysis completes, you get a notification with risk score, threat level, and detections.
3. High-risk files trigger a quarantine alert automatically.

URL scanning is not yet supported. Send files directly.

Self-hosting the bot

Set TELEGRAM_BOT_TOKEN in your .env before starting the stack:

TELEGRAM_BOT_TOKEN=your_bot_token_here

The bot starts automatically with the backend on docker compose up.

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | TRACE_URL | http://localhost:8090 | Trace instance base URL | | TRACE_TOKEN | (empty) | JWT token — required only for auth-protected endpoints |

Requirements

• Node.js 18+
• A running Trace instance (or use the live one at trace.akpinar.dev)