Mac Forensics MCP

🚀 mac_forensics-mcp

The MCP (Model Context Protocol) server designed for macOS Digital Forensics and Incident Response (DFIR). It streamlines forensic analysis by providing structured tools, reducing the context overhead when using LLMs for incident investigations.

🚀 Quick Start

This MCP server offers structured forensic analysis tools for macOS triage collections, which can reduce context overhead when investigating incidents with LLMs.

Key Benefits:

• Conduct structured queries instead of performing raw grep operations on massive files.
• Automatically normalize timestamps (from Mac Absolute Time to UTC).
• Utilize pre - built security event detection patterns.
• Perform cross - artifact correlation and build timelines.
• Implement pagination to avoid context overflow.
• Discover available artifacts.

There are 23 tools covering Unified Logs, FSEvents, Spotlight, Plists, SQLite databases, Extended Attributes, System Logs, and more.

📦 Installation

cd /opt/macOS/mac_forensics-mcp

# Create virtual environment and install dependencies
uv venv
uv pip install -e .

💻 Usage Examples

Basic Usage

# Discover artifacts in a triage
mac_list_artifacts(artifacts_dir="/path/to/triage")

# Find user deletion events
mac_unified_logs_security_events(
    log_path="/path/to/unified_logs.csv",
    event_type="user_deleted"
)

# Read deleted users from plist
mac_plist_read(
    plist_path="/path/to/com.apple.preferences.accounts.plist",
    key_path="deletedUsers"
)

Advanced Usage

# Deep investigation of user deletion
mac_investigate_event(
    artifacts_dir="/path/to/triage",
    event_type="user_deletion",
    target="username"
)

# Get Safari search history
mac_safari_searches(
    db_path="/path/to/History.db",
    query_filter="delete"
)

# Find external device activity
mac_parse_fsck_apfs_log(
    log_path="/path/to/fsck_apfs.log",
    external_only=True
)

# Search for specific volume
mac_parse_fsck_apfs_log(
    log_path="/path/to/fsck_apfs.log",
    volume_filter="suspicious_volume"
)

# Build user activity timeline
mac_get_user_timeline(
    artifacts_dir="/path/to/triage",
    username="username"
)

# Search FSEvents for file activity
mac_fsevents_search(
    fseventsd_path="/path/to/.fseventsd",
    path_filter="/Users/username",
    event_types=["created", "deleted"]
)

📚 Documentation

Claude Code Configuration

Option 1: Using claude mcp add (Recommended)

# Add to user settings (available in all projects)
claude mcp add mac-forensics -s user -- /opt/macOS/mac_forensics-mcp/.venv/bin/python -m mac_forensics_mcp.server

# Or add to current project only
claude mcp add mac-forensics -- /opt/macOS/mac_forensics-mcp/.venv/bin/python -m mac_forensics_mcp.server

To verify it was added:

claude mcp list

To remove:

claude mcp remove mac-forensics -s user

Option 2: Manual JSON Configuration

Add to ~/.claude/settings.json (user - level) or .claude/settings.json (project - level):

{
  "mcpServers": {
    "mac-forensics": {
      "command": "/opt/macOS/mac_forensics-mcp/.venv/bin/python",
      "args": ["-m", "mac_forensics_mcp.server"],
      "env": {}
    }
  }
}

Available Tools (23)

Discovery

Unified Logs

Plist Files

Databases

User Analysis

FSEvents

Extended Attributes & Spotlight

System Logs

Correlation & Investigation

Security Event Types

The mac_unified_logs_security_events tool supports these event types:

Investigation Event Types

The mac_investigate_event tool supports deep investigation of these event types:

Configuration

External Tool Paths

External forensic tools can be configured via environment variables. If not set, defaults to /opt/macOS/ paths.

Example with custom paths:

{
  "mcpServers": {
    "mac-forensics": {
      "command": "/opt/macOS/mac_forensics-mcp/.venv/bin/python",
      "args": ["-m", "mac_forensics_mcp.server"],
      "env": {
        "MAC_FORENSICS_UNIFIEDLOG_ITERATOR_PATH": "/custom/path/unifiedlog_iterator",
        "MAC_FORENSICS_FSEPARSER_PATH": "/custom/path/FSEParser.py",
        "MAC_FORENSICS_SPOTLIGHT_PARSER_PATH": "/custom/path/spotlight_parser.py"
      }
    }
  }
}

🔧 Technical Details

Dependencies

• Python 3.10+
• uv (for virtual environment and package management)
• mcp >= 1.0.0
• biplist (optional, for malformed plists)

External tools (optional, for parsing raw artifacts):

• unifiedlog_iterator - for parsing .logarchive bundles
• FSEParser - for parsing FSEvents (.fseventsd)
• spotlight_parser - for parsing Spotlight indexes

Architecture

mac_forensics_mcp/
├── server.py                # MCP server and tool definitions
├── config.py                # Configurable external tool paths
├── parsers/
│   ├── plist_parser.py      # Plist file parsing
│   ├── unified_log_parser.py # Unified log analysis
│   ├── sqlite_parser.py     # SQLite databases (KnowledgeC, Safari, TCC)
│   ├── fsevents_parser.py   # FSEvents parsing
│   ├── spotlight_parser.py  # Spotlight index parsing
│   ├── xattr_parser.py      # Extended attributes parsing
│   └── fsck_apfs_parser.py  # fsck_apfs.log parsing
├── correlation/
│   ├── timeline_builder.py  # Cross-artifact timeline correlation
│   └── event_investigator.py # Event-specific investigation
└── utils/
    ├── timestamps.py        # Mac/WebKit/HFS timestamp conversion
    └── discovery.py         # Artifact discovery

Forensic Value

This MCP server was developed based on real - world macOS DFIR investigations. Key forensic capabilities:

📄 License

No license information provided in the original document.

References

• SANS FOR518 Poster
• mac4n6 Artifacts Spreadsheet
• SUMURI Mac Forensics Best Practices Guide 2025
• Google Cloud - Reviewing macOS Unified Logs

Contributing

Based on lessons learned from macOS DFIR investigations. Additional tools and event patterns welcome.

Author

xtk

Built for the DFIR community.