Advanced Malware Analysis MCP Server

A professional, modular, and secure Model Context Protocol (MCP) server providing real-time threat intelligence and malware sample metadata for AI assistants (like Claude, Cursor, and Windsurf).

It integrates MalwareBazaar, VirusTotal, and Telegram, along with 10+ offline analysis and crypto utilities, enabling AI models to autonomously aid in defensive malware research.

🔒 Security First: This server provides metadata and IOCs only. The downloading of live malware binaries is permanently disabled by design. Path traversal protections ensure safe local file hashing.

---

🌟 Capabilities

• Real-Time Threat Intel: Query MalwareBazaar for recent samples, info by hash, or tags.
• VirusTotal Integration: Pull analysis stats, reputation, and file types with built-in API rate limiting.
• Advanced IOC Extraction: Extract and defang/refang IPs, Domains, URLs, Hashes, and Emails from unstructured text.
• YARA generation: Ask the AI to generate a template YARA rule based on a sample's exact signatures.
• Offline Crypto Lab: AES-GCM encryption (PBKDF2 600k iterations), SHA256/MD5 hashing, Shannon entropy analysis, and Hexdumps.
• Alerting: Dispatch findings directly to a Telegram channel.
• Secure Local Hashing: safely compute the SHA256 of local files to check against threat databases, strictly chrooted to allowed directories.

---

🚀 A-to-Z Installation & Deployment Guide

This server works with any standard MCP client. Below are instructions for building the project and deploying it either to Claude Desktop (Mac/Windows) or testing it visually on Linux/Ubuntu using the MCP Inspector.

Step 1: Prerequisites & Build

Ensure you have Node.js (v18 or newer) installed on your machine.

# 1. Clone the repository
git clone https://github.com/SaeidSec/Malware-Analysis-MCP-server.git
cd Malware-Analysis-MCP-server

# 2. Install dependencies
npm install

# 3. Build the TypeScript files
npm run build

Step 2: Obtain API Keys

• MB_AUTH_KEY (Required): Get your free Auth-Key at auth.abuse.ch.
• VT_API_KEY (Optional): VirusTotal API for vt_lookup. The free tier works perfectly (the server handles the 4 requests/minute limit).
• TG_BOT_TOKEN & TG_CHAT_ID (Optional): Telegram bot token and chat ID for the send_alert tool.
• ALLOWED_SCAN_DIRS (Highly Recommended): A comma-separated list of absolute paths (e.g., /home/user/Downloads,/tmp/malware). This strictly limits the check_local_file tool to prevent the AI from arbitrarily hashing personal files.

---

Deployment Option A: Claude Desktop (Mac / Windows)

Claude Desktop is currently the most popular way to use MCP servers.

1. Open your Claude Desktop config file:

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server configuration, pointing to your local built dist/index.js:

{
  "mcpServers": {
    "malware-analysis-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/Malware-Analysis-MCP-server/dist/index.js"
      ],
      "env": {
        "MB_AUTH_KEY": "YOUR_ABUSECH_AUTH_KEY",
        "VT_API_KEY": "YOUR_VT_API_KEY",
        "ALLOWED_SCAN_DIRS": "/Users/name/Downloads,/tmp/malware"
      }
    }
  }
}

3. Restart Claude Desktop completely. You can now prompt Claude to use your new threat intelligence tools!

---

Deployment Option B: Linux / Ubuntu (Web GUI via MCP Inspector)

Since Claude Desktop does not have an official Linux client yet, the best way to deploy and test the server on Ubuntu is using Anthropic's official MCP Inspector.

1. Create your environment variable file from the example:

cp example.env .env
nano .env # Add your API keys here

2. Run the MCP server directly into the Inspector:

npx -y @modelcontextprotocol/inspector node dist/index.js

3. Open the provided http://localhost:5173 link in your web browser and click Connect. You will be presented with a beautiful UI where you can visually test tools like get_recent or extract_iocs manually.

---

🛠️ Available MCP Tools

Threat Intelligence

• get_recent - Fetch latest MalwareBazaar entries
• get_info - Fetch precise sample metadata by SHA256
• get_taginfo - Fetch samples by tag (e.g., "TrickBot")
• virustotal_lookup - VT V3 detection stats and reputation
• suggest_analysis_blogs - Links to Malpedia, MITRE, and writeups

Advanced Analysis

• extract_iocs - Pulls domains, IPs, MS5/SHA256, Emails from text
• bulk_hash_check - Check multiple hashes against MalwareBazaar at once
• threat_summary - Generates a curated Markdown report for a specific sample
• generate_yara_template - Creates a starting point for YARA rules based on metadata
• defang_iocs / refang_iocs - Safe IOC sharing (e.g., 1[.]1[.]1[.]1)
• check_local_file - Securely hash a local file and query VT/MB

Offline Lab Utilities

• Encoding: base64_encode, base64_decode, url_encode, url_decode, hex_encode, hex_decode
• Compression: gzip_compress, gzip_decompress
• Crypto: aes_gcm_encrypt, aes_gcm_decrypt, hash_text
• Analysis: entropy (Shannon), hexdump_text

Alerting

• send_alert - Push message to Telegram (TG_BOT_TOKEN and TG_CHAT_ID env vars required)

---

🔒 Security Architecture

1. No Live Binaries: The get_file tool is disabled. The server cannot be tricked into executing or saving payload binaries.
2. Path Traversal Protection: Requests to check_local_file are resolved, normalized, and strictly checked against ALLOWED_SCAN_DIRS.
3. Hardened Crypto: The AES implementation uses PBKDF2 with 600,000 iterations (OWASP 2023 standard) and 16-byte random salts.
4. Rate Limiting: Protects your free-tier VirusTotal API key from accidental exhaustion by looping LLMs.
5. Streaming Hashing: Memory-safe streaming is used for hashing local files, preventing gigabyte-scale OOM crashes.

---

🧑‍💻 Development

# Install dependencies
npm install

# Run typechecker
npm run typecheck

# Build the project
npm run build

# Run in dev mode
npm run dev

See CONTRIBUTING.md for full guidelines.

License

MIT License. See LICENSE for details.