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

📂 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