Skip to main content
Glama
mac_forensics-mcp

mac_forensics-mcp

by x746b

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.

Related MCP server: SIFTAgent

Installation

cd /opt/macOS/mac_forensics-mcp

# Create virtual environment and install dependencies
uv venv
uv pip install --python .venv/bin/python3 -e .

Add to an MCP client

Register mac-forensics as a local stdio server in your MCP client's settings. Configuration format and location depend on the client. For clients that accept mcpServers JSON, use:

{
  "mcpServers": {
    "mac-forensics": {
      "command": "/absolute/path/to/mac_forensics-mcp/.venv/bin/python3",
      "args": ["-m", "mac_forensics_mcp.server"]
    }
  }
}

Replace the command with the absolute path to the virtual environment's Python interpreter. If your client uses a different configuration format, enter the same command and arguments through its MCP server settings. Use the client's MCP server list to confirm it connects. To remove the server, delete its entry from the client settings.

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 (user_created, ssh_session, 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 fsck_apfs.log for volume creation, external devices, anti-forensics

mac_fsck_apfs_stats

Get fsck_apfs.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 unifiedlog_iterator 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 spotlight_parser 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

Contributing

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


Author

xtk

Built for the DFIR community.

Available Tools

23 tools
mac_build_timelineB

Build a unified timeline from multiple forensic artifacts. Correlates events from unified logs, Safari history, KnowledgeC, and plists.

Inputs: artifacts_dir (required), limit, keyword, sources, +2 more.

mac_fsck_apfs_statsA

Get statistics about fsck_apfs.log: devices checked, volumes found, external devices, time range.

Inputs: log_path (required).

mac_fsevents_statsB

Get statistics about FSEvents records: total count, time range, event type counts.

Inputs: fseventsd_path (required).

mac_get_extended_attributesA

Get extended attributes (xattr) for a file. Contains true download times, quarantine info, and user-action dates more accurate than DB records.

Inputs: file_path (required), limit, recursive.

mac_get_user_accountsB

Get user accounts from a triage collection, including deleted users.

Inputs: artifacts_dir (required), include_deleted.

mac_get_user_timelineC

Build a timeline for a specific user account. Shows account creation, modification, deletion, and related activity.

Inputs: username (required), artifacts_dir (required), limit, time_end, +1 more.

mac_investigate_eventB

Deep investigation of a specific event type. Correlates evidence across multiple artifacts. Event types: user_deletion, user_creation, file_download, ssh_session, malware_execution, privilege_escalation.

Inputs: target (required), event_type (required), artifacts_dir (required), time_window_hours.

mac_knowledgec_app_usageB

Get application usage data from KnowledgeC.db. Shows what apps were used and when.

Inputs: db_path (required), limit, app_name, time_end, +1 more.

mac_list_artifactsB

Discover available forensic artifacts in a macOS triage collection. Returns inventory of logs, databases, plists, and user profiles.

Inputs: artifacts_dir (required).

mac_parse_fsck_apfs_logB

Parse fsck_apfs.log to find volume creation, external device connections, and anti-forensics activity. Shows APFS volume formatting operations with timestamps.

Inputs: log_path (required), limit, time_end, time_start, +4 more.

mac_plist_readB

Read and parse a macOS plist file. Optionally extract specific key path.

Inputs: plist_path (required), key_path.

mac_plist_timestampsB

Extract all timestamp values from a plist file with UTC conversion.

Inputs: plist_path (required).

mac_quarantine_eventsA

Get quarantine events (file downloads) from QuarantineEventsV2. Shows download source, app that downloaded, timestamp.

Inputs: db_path (required), limit, time_end, time_start, +1 more.

mac_safari_historyB

Get Safari browsing history with timestamps.

Inputs: db_path (required), limit, time_end, time_start, +2 more.

mac_safari_searchesB

Extract search queries from Safari history (Google, Bing, etc.).

Inputs: db_path (required), limit, time_end, time_start, +1 more.

mac_spotlight_statsB

Get statistics about a Spotlight index: total entries, content types, top directories.

Inputs: spotlight_path (required).

mac_tcc_permissionsB

Get TCC (Transparency, Consent, Control) permissions. Shows which apps have camera, mic, screen recording access.

Inputs: db_path (required), limit, client, service.

mac_unified_logs_security_eventsC

Get pre-defined security events from Unified Logs. Event types: user_created, user_deleted, user_modified, ssh_session, sudo_usage, auth_success, auth_failure, process_exec, gatekeeper, tcc_prompt, login, logout, screen_lock, screen_unlock, remote_login, persistence

Inputs: log_path (required), event_type (required), limit, offset, +2 more.

mac_unified_logs_statsA

Get statistics about a Unified Log file: time range, top subsystems, top processes, total entry count.

Inputs: log_path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 23 tools

    Disambiguation5/5

    Each tool targets a distinct forensic artifact or operation (e.g., timeline vs. statistics vs. search), with detailed descriptions that clearly differentiate them. There is no functional overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a uniform 'mac_verb_noun' pattern using snake_case, with verbs like build, get, search, parse, list, etc. No mixing of styles or inconsistent conventions.

    Tool Count4/5

    With 23 tools, the count is slightly above the typical 3-15 range but justified by the breadth of macOS forensics, covering logs, databases, plists, file system events, and more.

    Completeness5/5

    The toolkit covers major forensic artifacts: file system, logs, user accounts, browser history, application usage, permissions, and plists. Includes discovery and correlation tools, leaving no obvious gaps for standard triage.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      A governed MCP server for digital-forensics and incident-response (DFIR) work, exposing curated forensic tools (Volatility 3, Plaso, RegRipper, etc.) through a single FastMCP HTTP endpoint with bearer-token authentication and tamper-evident audit logging.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that transforms Claude Code into an autonomous DFIR analyst by providing typed, audited forensic tools for disk, memory, timeline, registry, and IOC analysis on the SANS SIFT Workstation.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server that wraps common forensic command-line tools for CTF/forensics competitions into MCP tools, enabling automated analysis of disk images, memory dumps, network captures, SQLite databases, archives, and steganography.
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Multi-tier memory forensics MCP server combining a fast Rust engine with Volatility3 coverage for analyzing memory dumps.
      15
      31 PyPI
      5
      MIT