SamiGPT

SamiGPT exposes security investigation and incident response capabilities through an MCP server, enabling automated triage, deep analysis, and CTI enrichment via a vendor-neutral API. You connect it to your case management, SIEM, EDR, and threat intel tools, then run automated workflows that scale across SOC tiers.

How to use

Connect SamiGPT to your MCP-compatible tools to enable automated case management, SIEM analysis, and CTI enrichment. You can run the MCP server locally and connect it to tooling such as Cursor or Claude Desktop, or you can use a remote MCP endpoint if provided.

Key usage patterns include starting the MCP server and then wiring your MCP clients to the server so they can invoke generic tools for case operations, SIEM investigations, EDR responses, and CTI lookups. Use the provided agent profiles and runbooks to triage new alerts, enrich data, perform deep investigations, and prepare cases for escalation.

How to install

Prerequisites: Python 3.9 or higher and the pip package manager.

Step 1: Create and activate a virtual environment.

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 2: Install dependencies.

pip install --upgrade pip
pip install -r requirements.txt

Step 3: Start the MCP server directly to connect SamiGPT tools to MCP-compatible clients.

python -m src.mcp.mcp_server

Step 4: (Optional) If you plan to connect the MCP server using Cursor or Claude Desktop, configure the corresponding MCP server entry in your client to point to this local server. Use the explicit command shown in the integration examples.

Additional configuration and integration options

Cursor integration provides a ready-made JSON snippet to connect SamiGPT as an MCP server. The snippet uses a stdio approach with the command and arguments needed to launch the server from within the Cursor environment.

{
  "mcpServers": {
    "sami-gpt": {
      "command": "python",
      "args": ["-m", "src.mcp.mcp_server"],
      "cwd": "/absolute/path/to/SamiGPT"
    }
  }
}

Claude Desktop integration follows a similar pattern, enabling you to run SamiGPT via the MCP server module from Claude Desktop by specifying the same command and arguments and the working directory where SamiGPT resides.

{
  "mcpServers": {
    "sami-gpt": {
      "command": "python",
      "args": ["-m", "src.mcp.mcp_server"],
      "cwd": "/absolute/path/to/SamiGPT"
    }
  }
}

Usage examples of core capabilities

The following examples illustrate how you interact with the MCP server through the available tools. Use these as a reference when building your automation and playbooks.

# List all open cases
cases = list_cases(status="open")

# Review a specific case
case = review_case(case_id="123")

# Add an observable to a case
attach_observable_to_case(
    case_id="123",
    observable_type="ip",
    observable_value="192.168.1.100",
    description="Suspicious source IP"
)

Agent profiles and runbooks

SamiGPT ships with pre-configured agent profiles that cover SOC1 and SOC2 workflows. SOC1 handles initial alert triage and enrichment, while SOC2 performs deep investigations, SIEM analysis, and CTI enrichment to prepare cases for escalation.

Available tools

list_cases

List all cases with optional filters such as status, owner, or assignee.

review_case

Fetch and review a specific case by its ID to inspect details and observables.

attach_observable_to_case

Attach an observable to a case with a description to enrich context and enable triage.

search_security_events

Query security events from the SIEM with a time window and filters to support investigation.

get_file_report

Retrieve a file or hash report from the data sources for evidence gathering.

pivot_on_indicator

Pivot on an IO indicator to surface related events and context across data sources.

get_endpoint_summary

Obtain a summary of an endpoint's state and activity for quick assessment.

isolate_endpoint

Isolate a compromised endpoint to prevent lateral movement and contain the incident.

collect_forensic_artifacts

Collect targeted forensic artifacts from an endpoint for deeper analysis.

execute_as_agent

Run a specific agent profile against an alert to perform triage or investigation steps.

execute_runbook

Run a predefined runbook against an alert or case to automate steps.