Skip to main content
Glama
TheHive FastMCP

TheHive FastMCP

by Hoopshaker

TheHive MCP Server (FastMCP)

Ce dépôt contient un serveur MCP (Model Context Protocol) générique et performant pour TheHive (plateforme d'orchestration et de réponse aux incidents de sécurité).

Il permet à des agents IA ou assistants de sécurité (comme Claude Desktop ou d'autres passerelles MCP) de manipuler et de requêter de manière sécurisée les Cases, Alerts, Observables (IoCs) et Tasks dans TheHive.

⚙️ Configuration

Le serveur s'appuie exclusivement sur des variables d'environnement pour sa configuration :

Variable

Description

Obligatoire

Valeur par défaut

THEHIVE_URL

URL de base de votre instance TheHive (ex: https://thehive.votre-domaine.com).

Oui

-

THEHIVE_API_KEY

Clé API de l'utilisateur (Bearer Token).

Oui

-

THEHIVE_VERIFY_SSL

Activer ou désactiver la vérification du certificat SSL. Utile en environnement auto-hébergé.

Non

true

THEHIVE_ORG

Nom de l'organisation cible (ajoute le header X-Organisation).

Non

-


Related MCP server: falcon-mcp

🛠️ Utilisation avec Docker

Ce serveur MCP est publié automatiquement sur GitHub Container Registry (GHCR). Vous pouvez l'utiliser directement sans cloner le code source ou construire l'image vous-même : Docker s'occupe de tout télécharger de manière transparente au premier lancement.

1. Exécution directe en ligne de commande

Comme le protocole MCP fonctionne via les flux d'entrée/sortie standard (stdio), vous devez exécuter le conteneur en mode interactif (-i) et sans allouer de pseudo-TTY (-t n'est pas utilisé pour éviter de polluer les flux avec des caractères d'échappement ANSI) :

docker run -i --rm \
  -e THEHIVE_URL="https://thehive.votre-domaine.com" \
  -e THEHIVE_API_KEY="VOTRE_CLE_API" \
  -e THEHIVE_VERIFY_SSL="false" \
  ghcr.io/hoopshaker/thehive-fastmcp:latest

2. Configuration pour les clients MCP (Gemini / Claude Desktop)

Pour connecter ce serveur automatiquement à votre client MCP (comme l'extension Gemini MCP ou Claude Desktop), ajoutez cette configuration à votre fichier de configuration (gemini-config.json ou claude_desktop_config.json) :

{
  "mcpServers": {
    "thehive": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "THEHIVE_URL=https://thehive.votre-domaine.com",
        "-e", "THEHIVE_API_KEY=VOTRE_CLE_API",
        "-e", "THEHIVE_VERIFY_SSL=false",
        "ghcr.io/hoopshaker/thehive-fastmcp:latest"
      ]
    }
  }
}

🔨 Build local (Optionnel / Développement)

Si vous souhaitez modifier le code ou construire l'image Docker vous-même localement :

  1. Depuis la racine du projet, construisez l'image :

    docker build -t thehive-fastmcp .
  2. Exécutez-la en remplaçant la référence GHCR par votre tag local :

    docker run -i --rm \
      -e THEHIVE_URL="https://thehive.votre-domaine.com" \
      -e THEHIVE_API_KEY="VOTRE_CLE_API" \
      thehive-fastmcp

🔧 Outils Exposés (Tools)

Une fois connecté, le serveur MCP expose les outils suivants :

📁 Cases (Dossiers d'incident)

  • get_case(id_or_name) : Récupère les détails complets d'un dossier par ID (ex: ~1234) ou numéro.

  • create_case(title, description, severity, tags, tlp, pap, flag) : Crée un nouveau dossier d'incident.

  • search_cases(title, severity, tags, status, limit) : Recherche des dossiers selon plusieurs critères.

🚨 Alerts (Alertes de sécurité)

  • get_alert(alert_id) : Récupère les détails complets d'une alerte.

  • create_alert(type_name, source, source_ref, title, description, severity, tags, tlp, pap) : Crée une alerte provenant d'un SIEM/EDR.

  • search_alerts(title, severity, tags, status, limit) : Recherche des alertes.

🔍 Observables (IoCs)

  • create_observable(case_id, data_type, data, message, tags, tlp, pap, ioc) : Ajoute un observable (ex: IP, domaine, hash) à un dossier.

  • get_case_observables(case_id, limit) : Liste tous les observables liés à un dossier.

📋 Tasks & Logs (Tâches d'investigation)

  • create_task(case_id, title, description, group, assignee) : Ajoute une tâche à accomplir dans un dossier d'incident.

  • get_case_tasks(case_id, limit) : Liste les tâches d'un dossier.

  • add_task_log(task_id, message) : Ajoute une note de progression ou un compte-rendu textuel à une tâche.


💻 Développement Local (sans Docker)

Si vous souhaitez lancer ou déboguer le serveur localement en utilisant uv :

  1. Installez uv si ce n'est pas déjà fait.

  2. Créez un environnement virtuel et installez les dépendances :

    uv sync
  3. Exportez vos variables d'environnement :

    export THEHIVE_URL="https://..."
    export THEHIVE_API_KEY="..."
    export THEHIVE_VERIFY_SSL="false"
  4. Lancez le serveur MCP :

    uv run python -m thehive_mcp.server

🧪 Test Manuel du Protocole JSON-RPC (Handshake)

Puisque le protocole MCP communique via des messages JSON-RPC 2.0 sur l'entrée standard (stdin), vous pouvez tester manuellement le serveur en saisissant directement les messages d'initialisation du handshake MCP dans votre terminal.

Étape 1 : Lancer l'initialisation

Une fois le serveur démarré, saisissez cette requête JSON-RPC d'initialisation et faites Entrée :

{"jsonrpc": "2.0", "id": 0, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}

Le serveur va répondre avec un bloc JSON contenant ses métadonnées et ses capacités.

Étape 2 : Confirmer l'initialisation (Notification)

Envoyez ensuite cette notification (sans id) pour finaliser le handshake :

{"jsonrpc": "2.0", "method": "notifications/initialized"}

Le serveur est maintenant initialisé et prêt à recevoir des commandes.

Étape 3 : Lister les outils disponibles

Vous pouvez désormais requêter la liste des outils :

{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}

Le serveur répondra avec la liste complète des outils TheHive (get_case, create_case, etc.) décrits au format JSON.

Available Tools

11 tools
add_task_logA

Add a progress log entry (log note) to an existing Task.

Args: task_id (str): The unique ID of the Task. message (str): Log message (describing progress, results, or notes). Supports markdown.

Inputs: message (required), task_id (required). Returns: result

create_alertA

Create a new Alert in TheHive. Alerts represent potential incidents fetched from SIEMs, emails, etc.

Args: type_name (str): Type of the alert (e.g., 'SIEM', 'Phishing', 'EDR'). source (str): Source/provider of the alert (e.g., 'Splunk', 'Wazuh'). source_ref (str): Unique reference ID from the source system. title (str): Title of the alert. description (str): Detailed markdown-supported description. severity (int): Severity level: 1 (Low), 2 (Medium), 3 (High), 4 (Critical). Default is 2. tags (List[str], optional): List of tags to categorize the alert. tlp (int): Traffic Light Protocol level (0 to 4). Default is 2. pap (int): Permissible Action Protocol level (0 to 3). Default is 2.

Inputs: title (required), source (required), type_name (required), source_ref (required), +5 more. Returns: result

create_caseA

Create a new empty security incident Case in TheHive.

Args: title (str): Title of the case. description (str): Detailed markdown-supported description of the case. severity (int): Severity level: 1 (Low), 2 (Medium), 3 (High), 4 (Critical). Default is 2. tags (List[str], optional): List of tags to categorize the case. tlp (int): Traffic Light Protocol level: 0 (White), 1 (Green), 2 (Amber), 3 (Amber+Strict), 4 (Red). Default is 2. pap (int): Permissible Action Protocol level: 0 (White), 1 (Green), 2 (Amber), 3 (Red). Default is 2. flag (bool): Mark the case as flagged/starred. Default is False.

Inputs: title (required), description (required), pap, tlp, +3 more. Returns: result

create_observableA

Add an Observable (IoC/Indicator of Compromise) to an existing Case.

Args: case_id (str): The unique ID of the target Case. data_type (str): Type of observable (e.g., 'ip', 'domain', 'hash', 'mail', 'url'). data (str): The actual observable value (e.g. '192.168.1.1' or 'bad-domain.com'). message (str, optional): A description or comment regarding this observable. tags (List[str], optional): List of tags to add to the observable. tlp (int): Traffic Light Protocol level (0 to 4). Default is 2. pap (int): Permissible Action Protocol level (0 to 3). Default is 2. ioc (bool): Whether to mark this observable as an active Indicator of Compromise. Default is False.

Inputs: data (required), case_id (required), data_type (required), ioc, +4 more. Returns: result

create_taskB

Create a new Task inside an existing Case for tracking investigation steps.

Args: case_id (str): The unique ID of the target Case. title (str): Title of the task. description (str, optional): Detailed explanation of the task. group (str, optional): Group category for the task. assignee (str, optional): Login/email of the user assigned to this task.

Inputs: title (required), case_id (required), group, assignee, +1 more. Returns: result

get_alertA

Get detailed information about a specific alert by its ID.

Args: alert_id (str): The unique ID of the alert.

Inputs: alert_id (required). Returns: result

get_caseB

Get detailed information about a specific case by its ID or case number.

Args: id_or_name (str): The unique ID of the case (starts with '~') or the case number.

Inputs: id_or_name (required). Returns: result

get_case_observablesA

List all observables associated with a specific Case.

Args: case_id (str): The unique ID or name/number of the Case. sort (str, optional): Field to sort by. Use '-' prefix for descending (e.g., '-_createdAt' or '-_updatedAt'). created_after (str, optional): Filter observables created after this date (ISO 8601 or timestamp in ms). created_before (str, optional): Filter observables created before this date (ISO 8601 or timestamp in ms). limit (int): Maximum number of observables to return. Default is 50.

Inputs: case_id (required), sort, limit, created_after, +1 more. Returns: result

get_case_tasksA

List all tasks associated with a specific Case.

Args: case_id (str): The unique ID or name/number of the Case. sort (str, optional): Field to sort by. Use '-' prefix for descending (e.g., '-_createdAt' or '-_updatedAt'). created_after (str, optional): Filter tasks created after this date (ISO 8601 or timestamp in ms). created_before (str, optional): Filter tasks created before this date (ISO 8601 or timestamp in ms). limit (int): Maximum number of tasks to return. Default is 50.

Inputs: case_id (required), sort, limit, created_after, +1 more. Returns: result

search_alertsA

Search for Alerts in TheHive with advanced filtering.

Args: title (str, optional): Substring match on the Alert title. severity (int, optional): Filter by exact severity level (1 to 4). tags (List[str], optional): Filter by tags (requires all tags to match). status (str, optional): Filter by status (e.g. 'New', 'Imported', 'Ignored'). sort (str, optional): Field to sort by. Use '-' prefix for descending (e.g., '-_createdAt' or '-_updatedAt'). created_after (str, optional): Filter alerts created after this date (ISO 8601 or timestamp in ms). created_before (str, optional): Filter alerts created before this date (ISO 8601 or timestamp in ms). limit (int): Maximum number of alerts to return. Default is 10.

Inputs: sort, tags, limit, title, +4 more. Returns: result

search_casesA

Search for Cases in TheHive with advanced filtering capabilities.

Args: title (str, optional): Substring match on the Case title. severity (int, optional): Filter by exact severity level (1 to 4). tags (List[str], optional): Filter by tags (requires all tags to match). status (str, optional): Filter by status (e.g. 'Open', 'Resolved'). sort (str, optional): Field to sort by. Use '-' prefix for descending (e.g., '-_createdAt' or '-_updatedAt'). created_after (str, optional): Filter cases created after this date (ISO 8601 or timestamp in ms). created_before (str, optional): Filter cases created before this date (ISO 8601 or timestamp in ms). limit (int): Maximum number of cases to return. Default is 10.

Inputs: sort, tags, limit, title, +4 more. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct entity (alert, case, task, observable) and action (create, get, search, add). There is no overlap in functionality; for instance, create_alert and create_case are clearly different, and get_alert vs get_case are unambiguously separate.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case (e.g., create_alert, get_case, search_cases). There are no deviations, mixed conventions, or ambiguous verbs.

    Tool Count5/5

    With 11 tools, the server covers the essential operations for TheHive (alerts, cases, tasks, observables). The count is balanced—neither too few to be useless nor too many to be overwhelming.

    Completeness3/5

    The server provides create, get, and search operations for alerts and cases, but lacks update and delete operations for both. Additionally, there is no tool to promote an alert to a case or to close/merge cases. These gaps are notable for full lifecycle management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that connects AI agents to the CrowdStrike Falcon platform for intelligent security analysis and automation across various security modules. It provides programmatic access to detections, incidents, host management, and threat intelligence to enhance security operations within agentic workflows.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      An MCP server for the Cortex observable analysis and active response engine. It enables LLMs to automate security investigations by running analyzers on observables like IPs and URLs and executing automated response actions.
      31
      11 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      An MCP server that exposes a 60+ tool security and threat-intel stack to AI agents, enabling secret scanning, Sigma rule generation, ransomware lookup, OSINT, and deep research.
      1
      MIT