MCP Forensic Toolkit is a secure, AI-ready local server for digital forensics, built using the Model Context Protocol (MCP). It exposes semantically meaningful tools to analyze logs, verify file integrity, and generate audit-grade forensic reports. Designed for analysts and LLMs alike, it enables automated investigation with precision and safety.
Features
- Structured log triage using keyword-based scanning (
scan_syslog) - File metadata extraction and SHA-256 hashing (
file_metadata) - Recursive integrity scanning with directory hashing (
hash_directory) - Correlation engine linking file modifications to log events (
correlate_file_and_logs) - Human-readable forensic reporting (
generate_forensic_report) - Secure access control via
SAFE_BASE and sandboxed environment - Built-in LLM prompts for guided reasoning and forensic tasks
Screenshot
This example demonstrates a successful correlation analysis between a file and system log entries using the generate_forensic_report tool:
Getting Started
Prerequisites
- Python 3.10+
- Poetry or pip
- MCP CLI (
pip install modelcontext or follow setup guide) .env file with SAFE_BASE defined
Installation
Dependencies
- Python >= 3.10
- Poetry (recommended) or pip for dependency management
- Key Python packages installed automatically:
- modelcontext
- fastapi
- uvicorn
- python-dotenv
- typing-extensions
Using Poetry (recommended)
# Clone the repo
git clone https://github.com/axdithyaxo/mcp-forensic-toolkit.git
cd mcp-forensic-toolkit
# Install Poetry if not already installed
curl -sSL https://install.python-poetry.org | python3 -
# Install dependencies and create virtual environment automatically
poetry install
# Activate the Poetry shell
poetry shell
# Create and configure environment variables
cp .env.example .env
# Edit .env and set your SAFE_BASE (e.g. /Users/yourname/Desktop)
Using Python venv and pip (alternative)
# Clone the repo
git clone https://github.com/axdithyaxo/mcp-forensic-toolkit.git
cd mcp-forensic-toolkit
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows use `.venv\Scripts\activate`
# Install dependencies
pip install -r requirements.txt
# Create and configure environment variables
cp .env.example .env
# Edit .env and set your SAFE_BASE (e.g. /Users/yourname/Desktop)
Note for Windows users:
# Use .venv\Scripts\activate to activate the virtual environment instead of source .venv/bin/activate.
Usage
Start the Server
Make sure you have the MCP CLI installed (pip install modelcontext) and dependencies installed (poetry install or pip install -r requirements.txt).
Then start the server:
mcp dev mcp_forensic_toolkit/server.py
---
### Access via MCP Inspector
Use the MCP Inspector or visit:
http://127.0.0.1:6274
You can then:
* Run tools (`scan_syslog`, `file_metadata`, etc.)
* Execute prompts for analysis
* View and inspect structured output
---
## CLI Demo (Optional)
You can run a command-line demo as follows:
```bash
python cli_demo.py ~/Desktop/test_hit.txt correlation
If correlation is found, output includes:
File: /Users/...
Keyword searched in logs: 'correlation'
File modified at: ...
Matching log entries:
- ...
- ...
Correlation found: Yes
Otherwise:
Example Workflow
- Modify or inspect a file within
SAFE_BASE. - Run
generate_forensic_report or the CLI tool. - Use MCP Inspector or LLM to interpret results.
- Example match:
{
"filename": "/Users/you/Desktop/test_hit.txt",
"file_modified_time": "2025-06-08T00:26:04.714230",
"log_hits": [
"logger: correlation test for test_hit.txt",
"log run noninteractively, args: ..."
],
"correlation_found": true
}
Environment Variables
| Variable | Description |
|---|
SAFE_BASE | Restricts all file operations to this path. |
Example .env.example:
SAFE_BASE=/Users/yourname/Desktop
Security Considerations
- All tools validate paths against
SAFE_BASE - System logs are accessed in a read-only way
- Tools gracefully handle permission errors and malformed inputs
- CLI interface avoids unsafe globbing or directory traversal
Testing
Run unit tests:
Or with pytest:
Usage Examples
Example: "Investigate File" Prompt in Claude Desktop
Prompt Given
Use the investigate-file prompt to analyze the file at "/Users/username/Desktop/test_hit.txt".
Provide the file size, creation and modification times, and SHA-256 hash.
Assess if there are any signs of tampering or suspicious characteristics.
Example Response
File Investigation Report
- File Path: /Users/username/Desktop/test_hit.txt
- File Size: 9 bytes
- Created: June 8, 2025 at 00:26:04.733792 UTC
- Modified: June 8, 2025 at 00:26:04.714230 UTC
- SHA-256 Hash: 9b7729b1ccfe223076659db07b7f0bb888e139907bb8d7019560166176953fcb
Analysis and Assessment
File Characteristics:
- This is a very small file (only 9 bytes), likely containing minimal text content
- The file was created and modified almost simultaneously, with the modification timestamp actually preceding the creation timestamp by about 19 milliseconds - this is unusual but can occur due to filesystem timing precision differences
Temporal Analysis:
- Creation and modification occurred at 00:26:04 UTC
- No specific log entries were found relating to this file’s creation or modification in the system logs
- The logs show normal system activity around that time period, primarily power management and Claude desktop application activity
Security Assessment:
There are no apparent signs of tampering or suspicious characteristics:
- File Size: The 9-byte size is consistent with a small text file
- Timestamps: While the modification time slightly precedes creation time, this is a known filesystem behavior and not indicative of tampering
- Hash Integrity: The SHA-256 hash provides a baseline for future integrity verification
- System Logs: No suspicious file system activity or security events were detected around the creation time
- Location: The file is in a standard user Desktop directory, which is a normal location for user files
Recommendations:
- The file appears to be legitimate with no signs of tampering
- Store the SHA-256 hash for future integrity verification
- Monitor for any unexpected changes by periodically checking its hash
Additional Example Prompts
1. Triage System Logs Prompt
Use the triage-system-logs prompt to search the system logs for the keyword “error”.
Summarize the most relevant log entries indicating warnings or security events.
Advise if any immediate action is recommended.
2. Correlate Log and File Prompt
Use the correlate-log-and-file prompt to analyze the file “/Users/username/Desktop/test_hit.txt” and search system logs for the keyword “correlation”.
Determine if the file modification times align with suspicious log events.
Explain the correlation and its forensic implications.
3. Explain Correlation Prompt
Use the explain-correlation prompt with the file “/Users/username/Desktop/test_hit.txt” and keyword “correlation”.
Interpret the log hits and file metadata.
Provide a concise forensic reasoning summary (under 100 words).
Forensic Analysis Report
A detailed forensic analysis report demonstrating usage and output of the toolkit is available:
This report provides an example of the kind of structured output generated by the toolkit’s tools and prompts.
Using with Claude Desktop
To connect MCP Forensic Toolkit with Claude Desktop:
- Create a config file, e.g.,
claude_config.json, with the following content (adjust paths accordingly):
{
"mcpServers": {
"MCP Forensic Toolkit": {
"command": "/path/to/your/venv/bin/mcp",
"args": ["run", "/path/to/mcp_forensic_toolkit/server.py"]
}
}
}
Demo Video
Watch the MCP Forensic Toolkit demo video here:
Demo Video on Google Drive
License
MIT License
Acknowledgments
- The Model Context Protocol (MCP) team and community for creating an innovative standard enabling interoperable AI tool integration.
- The FastMCP Python SDK developers for providing a robust and user-friendly framework to build MCP servers.
- The broader open-source and digital forensics communities for inspiring secure and effective AI-driven investigative tooling.
- Projects and initiatives focused on secure AI-agent interfacing and infrastructure automation, which shaped the vision behind this toolkit.