mac_forensics-mcp
This MCP server provides structured macOS DFIR forensic analysis tools for triage collections, enabling discovery, searching, timeline building, and event investigation.
Discover available artifacts in a triage collection
Search and analyze macOS Unified Logs with regex, filters, stats, and pre-defined security events
Read, search, and extract timestamps from plist files
Query SQLite databases: KnowledgeC app usage, Safari history/searches, TCC permissions, and quarantine/download events
List user accounts (including deleted) and build per-user activity timelines
Retrieve extended attributes (xattr) for files/directories
Search and get stats from Spotlight indexes
Search and get stats from FSEvents records
Parse and get stats from fsck_apfs.log for volume creation/external device activity
Build unified cross-artifact timelines and deeply investigate specific event types (user deletion/creation, file download, SSH session, malware execution, privilege escalation)
Provides tools for forensic analysis of macOS systems, including user account forensics, file activity tracking, security event detection, and cross-artifact correlation from triage collections.
Enables extraction of Safari browsing history and search queries from Safari's database.
Allows searching the Spotlight index for file metadata and retrieving index statistics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mac_forensics-mcp search for failed authentication events in the last 24 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Discover available artifacts in a triage collection |
Unified Logs
Tool | Description |
| Search logs with regex, filters, time range |
| Get pre-defined security events (user_created, ssh_session, etc.) |
| Get log statistics: time range, top subsystems |
Plist Files
Tool | Description |
| Read and parse plist, optionally extract key path |
| Search for keys matching pattern |
| Extract all timestamp values with UTC conversion |
Databases
Tool | Description |
| App usage from KnowledgeC.db |
| Safari browsing history |
| Extract search queries from Safari |
| TCC permissions (camera, mic, screen recording) |
| File download history |
User Analysis
Tool | Description |
| List users including deleted accounts |
| Build timeline for specific user account |
FSEvents
Tool | Description |
| Search file system events (create, delete, modify, rename) |
| Get FSEvents statistics |
Extended Attributes & Spotlight
Tool | Description |
| Get xattr for file (quarantine, download URL, etc.) |
| Search Spotlight index for file metadata |
| Get Spotlight index statistics |
System Logs
Tool | Description |
| Parse fsck_apfs.log for volume creation, external devices, anti-forensics |
| Get fsck_apfs.log statistics: devices, volumes, time range |
Correlation & Investigation
Tool | Description |
| Build unified timeline from multiple artifacts |
| Deep investigation with evidence correlation |
Security Event Types
The mac_unified_logs_security_events tool supports these event types:
Event Type | Description |
| User account creation |
| User account deletion |
| User account changes |
| SSH connections |
| Sudo command execution |
| Successful authentication |
| Failed authentication |
| Process execution |
| Gatekeeper/quarantine events |
| TCC permission prompts |
| User login |
| User logout |
| Screen lock events |
| Screen unlock events |
| Remote Login service |
| Persistence mechanisms |
Investigation Event Types
The mac_investigate_event tool supports deep investigation of these event types:
Event Type | Description |
| Investigate user account deletion with timeline and evidence correlation |
| Investigate user account creation |
| Investigate file downloads (quarantine, xattr, browser history) |
| Investigate SSH session activity |
| Investigate potential malware execution |
| 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 |
|
| Path to unifiedlog_iterator binary |
|
| Path to FSEParser script |
|
| 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 bundlesFSEParser- 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 discoveryForensic Value
This MCP server was developed based on real-world macOS DFIR investigations. Key forensic capabilities:
Capability | Tools |
User account forensics |
|
File activity tracking |
|
Download analysis |
|
Security event detection |
|
External device detection |
|
Cross-artifact correlation |
|
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 toolsmac_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_searchC
Search FSEvents records for file system activity. Shows file creation, deletion, modification, and rename operations.
Inputs: fseventsd_path (required), limit, offset, time_end, +4 more.
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_searchC
Search for keys matching a pattern across a plist file.
Inputs: pattern (required), plist_path (required).
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_searchB
Search Spotlight index for file metadata. Contains info even for deleted files.
Inputs: spotlight_path (required), inode, limit, offset, +5 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_searchB
Search macOS Unified Logs with filters. Supports regex patterns, subsystem/category/process filters, and time ranges.
Inputs: query (required), log_path (required), limit, offset, +4 more.
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
Scored across 23 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Syslog receiver and MCP server for homelab log intelligence.
Syslog receiver and MCP server for homelab log intelligence.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceA 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
- AlicenseNot gradedqualityDmaintenanceAn 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
- AlicenseNot gradedqualityDmaintenanceA 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.1MIT
- AlicenseBqualityBmaintenanceMulti-tier memory forensics MCP server combining a fast Rust engine with Volatility3 coverage for analyzing memory dumps.1531 PyPI5MIT