Self-Assembling Forensic MCP Server (FastMCP / Python)

A modular Digital Forensics and Incident Response (DFIR) Model Context Protocol (MCP) server built with Python and FastMCP (mcp>=2.0.0).

It dynamically discovers host & container forensic utilities at startup and automatically self-assembles functional tools, resources, and triage prompts for local LLMs and AI agents (Ollama, Claude, Cursor, Antigravity, etc.).

---

🌟 Features

• 🔍 Dynamic Capability Discovery: Probes host environment paths, installed binaries (exiftool, strings, volatility3, binwalk, tshark, objdump, gdb, yara), and Docker runtimes. Missing tools are gracefully reported without crashing.
• 🧩 Self-Assembling Tool Primitives: Automatically registers only the tools available in the host environment.
• 🛡️ Air-Gapped & Offline Ready: Built-in offline threat intelligence database with known sample signatures (EICAR, WannaCry, Mimikatz) for secure, zero-data-leakage incident response.
• 📋 Tamper-Evident Chain of Custody: Every tool execution, inspected artifact, SHA-256 checksum, and action parameter is cryptographically hashed and logged to an append-only ledger (evidence/chain_of_custody.jsonl).
• 🩺 Self-Reporting Health & Resources: Real-time capability matrix (forensics://capabilities), custody logs (forensics://custody), and system health (forensics://health).
• ⚡ Dual Transport: Supports standard STDIO for native MCP clients (Cursor, Claude, Antigravity) and SSE/HTTP for web LLM agents (Ollama, Open WebUI).

---

🚀 Quick Start

1. Prerequisites

• Python 3.10+ (or uv)

2. Run the Server

Option A: Native STDIO Transport (For Local Agents / Cursor / Claude)

cd /home/b47m4n/Projects/forensics-mcp-framework
uv run src/server.py

Option B: SSE / HTTP Transport (For Web / Remote LLMs)

cd /home/b47m4n/Projects/forensics-mcp-framework
uv run src/server.py --transport sse --port 8000

---

🔌 Connecting to Local LLMs & Agents

1. Antigravity / Claude / Cursor (claude_desktop_config.json / mcp.json)

{
  "mcpServers": {
    "forensic-analyzer": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/b47m4n/Projects/forensics-mcp-framework",
        "run",
        "src/server.py"
      ]
    }
  }
}

2. Local LLM via Ollama + MCP

Connect your local model (e.g. llama3.1, qwen2.5-coder) via SSE endpoint: http://localhost:8000/sse

---

🛠️ Discovered Tool Catalog

Tool	Category	Dynamic Condition	Description
extract_metadata	Metadata & Files	Always Available	Computes hashes (MD5/SHA256), EXIF tags, and detects MIME mismatches
extract_strings	Static Analysis	Always Available	Extracts printable ASCII & Unicode strings
scan_iocs	Threat Detection	Always Available	Scans for C2 URLs, IP addresses, Base64 blobs, command execution
check_threat_intel	Threat Intel	Always Available	Checks hashes against offline signatures and optional live APIs
system_health_check	Diagnostics	Always Available	Health status, storage check, and tool readiness
windows_image_info	Memory Forensics	vol or Docker	Volatility 3 windows.info
windows_pslist	Memory Forensics	vol or Docker	Volatility 3 windows.pslist
windows_pstree	Memory Forensics	vol or Docker	Volatility 3 windows.pstree
windows_netscan	Memory Forensics	vol or Docker	Volatility 3 windows.netscan
windows_malfind	Memory Forensics	vol or Docker	Volatility 3 windows.malfind (injected code)
binwalk_scan	File Carving	binwalk present	Firmware signature and filesystem carving
pcap_analyze	Network Forensics	tshark present	Dissects PCAP network packet captures
binary_disassemble	Reverse Eng	objdump present	Disassembles binary machine instructions
gdb_inspect	Debugging	gdb present	Automated batch debugging inspection
yara_scan	Signature Match	yara present	Scans evidence against YARA rule files

---

📂 Project Architecture

forensics-mcp-framework/
├── pyproject.toml
├── .env.example
├── README.md
├── evidence/                  # Evidence locker & chain of custody ledger
│   ├── suspect_photo.jpg
│   ├── eicar_test.com
│   └── chain_of_custody.jsonl
└── src/
    ├── server.py              # Master FastMCP bootstrap & dynamic assembler
    ├── core/
    │   ├── discovery.py       # Host & container capability scanner
    │   ├── custody.py         # Tamper-evident append-only chain of custody
    │   └── health.py          # System diagnostics & health reporter
    ├── tools/
    │   ├── metadata.py        # ExifTool & MIME mismatch detector
    │   ├── strings_ioc.py     # String & IOC scanner (IP, URL, Base64, shell)
    │   ├── threat_intel.py    # Offline/online threat intelligence
    │   ├── memory_vol.py      # Volatility 3 memory analysis engine
    │   └── dynamic_cli.py     # CLI wrappers (binwalk, tshark, objdump, gdb)
    ├── resources/
    │   └── system_resources.py# MCP Resources
    └── prompts/
        └── triage_prompts.py  # Structured DFIR workflows