Mac Forensics Mcp

mac_forensics-mcp

MCP (Model Context Protocol) server for macOS Digital Forensics and Incident Response (DFIR).

Overview

This MCP server provides structured forensic analysis tools for macOS triage collections, reducing context overhead when investigating incidents with LLMs.

Key Benefits:

• Structured queries instead of raw grep through massive files
• Automatic timestamp normalization (Mac Absolute Time → UTC)
• Pre-built security event detection patterns
• Cross-artifact correlation and timeline building
• Pagination to avoid context overflow
• Artifact discovery to know what's available

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 .

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

| Tool | Description | |------|-------------| | mac_list_artifacts | Discover available artifacts in a triage collection |

Unified Logs

| Tool | Description | |------|-------------| | mac_unified_logs_search | Search logs with regex, filters, time range | | mac_unified_logs_security_events | Get pre-defined security events (usercreated, sshsession, etc.) | | mac_unified_logs_stats | Get log statistics: time range, top subsystems |

Plist Files

| Tool | Description | |------|-------------| | mac_plist_read | Read and parse plist, optionally extract key path | | mac_plist_search | Search for keys matching pattern | | mac_plist_timestamps | Extract all timestamp values with UTC conversion |

Databases

| Tool | Description | |------|-------------| | mac_knowledgec_app_usage | App usage from KnowledgeC.db | | mac_safari_history | Safari browsing history | | mac_safari_searches | Extract search queries from Safari | | mac_tcc_permissions | TCC permissions (camera, mic, screen recording) | | mac_quarantine_events | File download history |

User Analysis

| Tool | Description | |------|-------------| | mac_get_user_accounts | List users including deleted accounts | | mac_get_user_timeline | Build timeline for specific user account |

FSEvents

| Tool | Description | |------|-------------| | mac_fsevents_search | Search file system events (create, delete, modify, rename) | | mac_fsevents_stats | Get FSEvents statistics |

Extended Attributes & Spotlight

| Tool | Description | |------|-------------| | mac_get_extended_attributes | Get xattr for file (quarantine, download URL, etc.) | | mac_spotlight_search | Search Spotlight index for file metadata | | mac_spotlight_stats | Get Spotlight index statistics |

System Logs

| Tool | Description | |------|-------------| | mac_parse_fsck_apfs_log | Parse fsckapfs.log for volume creation, external devices, anti-forensics | | mac_fsck_apfs_stats | Get fsckapfs.log statistics: devices, volumes, time range |

Correlation & Investigation

| Tool | Description | |------|-------------| | mac_build_timeline | Build unified timeline from multiple artifacts | | mac_investigate_event | Deep investigation with evidence correlation |

Security Event Types

The mac_unified_logs_security_events tool supports these event types:

| Event Type | Description | |------------|-------------| | user_created | User account creation | | user_deleted | User account deletion | | user_modified | User account changes | | ssh_session | SSH connections | | sudo_usage | Sudo command execution | | auth_success | Successful authentication | | auth_failure | Failed authentication | | process_exec | Process execution | | gatekeeper | Gatekeeper/quarantine events | | tcc_prompt | TCC permission prompts | | login | User login | | logout | User logout | | screen_lock | Screen lock events | | screen_unlock | Screen unlock events | | remote_login | Remote Login service | | persistence | Persistence mechanisms |

Investigation Event Types

The mac_investigate_event tool supports deep investigation of these event types:

| Event Type | Description | |------------|-------------| | user_deletion | Investigate user account deletion with timeline and evidence correlation | | user_creation | Investigate user account creation | | file_download | Investigate file downloads (quarantine, xattr, browser history) | | ssh_session | Investigate SSH session activity | | malware_execution | Investigate potential malware execution | | privilege_escalation | Investigate privilege escalation attempts |

Usage Examples

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"
)

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"
)

Read deleted users from plist

mac_plist_read(
    plist_path="/path/to/com.apple.preferences.accounts.plist",
    key_path="deletedUsers"
)

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"]
)

Configuration

External Tool Paths

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

| Environment Variable | Default | Description | |---------------------|---------|-------------| | MAC_FORENSICS_UNIFIEDLOG_ITERATOR_PATH | /opt/macOS/unifiedlog_iterator | Path to unifiedlogiterator binary | | MAC_FORENSICS_FSEPARSER_PATH | /opt/macOS/FSEventsParser/FSEParser_V4.1.py | Path to FSEParser script | | MAC_FORENSICS_SPOTLIGHT_PARSER_PATH | /opt/macOS/spotlight_parser/spotlight_parser.py | Path to spotlightparser script |

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"
      }
    }
  }
}

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:

| Capability | Tools | |------------|-------| | User account forensics | mac_get_user_accounts, mac_get_user_timeline, mac_investigate_event | | File activity tracking | mac_fsevents_search, mac_spotlight_search | | Download analysis | mac_quarantine_events, mac_get_extended_attributes | | Security event detection | mac_unified_logs_security_events | | External device detection | mac_parse_fsck_apfs_log | | Cross-artifact correlation | mac_build_timeline, mac_investigate_event |

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.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: x746b
• Source: x746b/mac_forensics-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.