MCP Server for TheHive

An MCP (Model Context Protocol) server that provides AI models and automation tools with access to TheHive incident response platform.

Overview

This server acts as a bridge between MCP clients (like AI assistants) and TheHive, allowing them to:

Retrieve and analyze security alerts
Access case information
Promote alerts to cases
Perform incident response operations

Features

Available Tools

get_thehive_alerts - Retrieve a list of alerts from TheHive
- Optional limit parameter (default: 100)
- Returns formatted alert information including ID, title, severity, and status
get_thehive_alert_by_id - Get detailed information about a specific alert
- Required alert_id parameter
- Returns comprehensive alert details
get_thehive_cases - Retrieve a list of cases from TheHive
- Optional limit parameter (default: 100)
- Returns formatted case information
get_thehive_case_by_id - Get detailed information about a specific case
- Required case_id parameter
- Returns comprehensive case details
promote_alert_to_case - Promote an alert to a case
- Required alert_id parameter
- Returns information about the newly created case
create_thehive_case - Create a new case in TheHive
- Required title and description parameters
- Optional parameters: severity, tags, tlp, pap, status, assignee, case_template, start_date
- Returns information about the newly created case

Installation

Prerequisites

Access to a TheHive 5 instance
Valid TheHive API token

Downloading Pre-compiled Binaries

You can download pre-compiled binaries for various operating systems from the GitHub Releases page. Download the appropriate binary for your system, make it executable, and place it in your desired location.

Building from Source

git clone <repository-url>
cd mcp-server-thehive
cargo build --release

Configuration

The server requires the following environment variables:

THEHIVE_URL - TheHive API base URL (default: http://localhost:9000/api)
THEHIVE_API_TOKEN - TheHive API token (required)
VERIFY_SSL - Whether to verify SSL certificates (default: false)
RUST_LOG - Logging level (optional, e.g., debug, info)

Environment File

Create a .env file in the project root:

THEHIVE_URL=https://your-thehive-instance.com/api
THEHIVE_API_TOKEN=your-api-token-here
VERIFY_SSL=true
RUST_LOG=info

Getting a TheHive API Token

Log into your TheHive instance
Go to User Settings → API Keys
Click Create API Key
Copy the generated token and use it as THEHIVE_API_TOKEN

Usage

Running the Server

# Using cargo
cargo run

# Using the built binary
./target/release/mcp-server-thehive

Integration with MCP Clients

The server communicates over stdio using the MCP protocol. Configure your MCP client to use this server:

{
  "mcpServers": {
    "thehive": {
      "command": "/path/to/mcp-server-thehive",
      "env": {
        "THEHIVE_URL": "https://your-thehive-instance.com:9000/api",
        "THEHIVE_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Examples

Retrieving Recent Alerts

{
  "method": "tools/call",
  "params": {
    "name": "get_thehive_alerts",
    "arguments": {
      "limit": 10
    }
  }
}

Getting Alert Details

{
  "method": "tools/call",
  "params": {
    "name": "get_thehive_alert_by_id",
    "arguments": {
      "alert_id": "~123456"
    }
  }
}

Promoting an Alert to Case

{
  "method": "tools/call",
  "params": {
    "name": "promote_alert_to_case",
    "arguments": {
      "alert_id": "~123456"
    }
  }
}

Creating a New Case

{
  "method": "tools/call",
  "params": {
    "name": "create_thehive_case",
    "arguments": {
      "title": "Potential Malware Outbreak",
      "description": "Multiple endpoints reporting suspicious process activity.",
      "severity": 3,
      "tags": ["malware", "endpoint", "epp"],
      "tlp": 2,
      "assignee": "soc_level2"
    }
  }
}

Development

Project Structure

mcp-server-thehive/
├── src/
│   ├── main.rs              # Main server implementation
│   ├── lib.rs               # Library exports
│   └── thehive/
│       ├── mod.rs           # Module declarations
│       ├── client.rs        # TheHive API client
│       └── error.rs         # Error types
├── tests/
│   ├── bin/
│   │   └── mock_thehive_server.rs # Mock TheHive API server for testing
│   ├── integration_test.rs    # Integration tests
│   └── mcp_stdio_test.rs      # Stdio interface tests
├── Cargo.toml               # Dependencies and metadata
└── README.md                # This file

Dependencies

rmcp - MCP protocol implementation
thehive-client - TheHive API client library
tokio - Async runtime
reqwest - HTTP client
serde - Serialization framework
tracing - Logging and instrumentation

Testing

The project includes a comprehensive suite of integration tests that leverage a mock TheHive server. This mock server simulates the TheHive API, allowing for isolated and repeatable testing of the MCP server's functionality without requiring a live TheHive instance.

Running Tests:

# Run all tests (including integration tests that use the mock server)
cargo test

# Run tests with verbose logging (includes MCP server and mock server logs)
RUST_LOG=debug MCP_SERVER_THEHIVE_VERBOSE_TEST_LOGS=true cargo test

Security Considerations

Store API tokens securely (use environment variables or secure credential stores)
Never commit API tokens to version control
Enable SSL verification in production environments
Limit network access to TheHive instance
Use least-privilege API tokens for TheHive access
Monitor and log all API interactions
Rotate API tokens regularly

Troubleshooting

Common Issues

Connection Refused
- Verify THEHIVE_URL is correct
- Check network connectivity to TheHive instance
- Ensure TheHive is running and accessible
Authentication Failed
- Verify THEHIVE_API_TOKEN is correct and not expired
- Check if the API token has necessary permissions
- Ensure the token is properly formatted
SSL Certificate Errors
- Set VERIFY_SSL=false for testing (not recommended for production)
- Install proper SSL certificates
- Use valid certificate authority

Logging

Enable debug logging for troubleshooting:

RUST_LOG=debug cargo run

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

thehive-client-rs - Rust client library for TheHive API
mcp-server-cortex - MCP server for Cortex
mcp-server-wazuh - MCP server for Wazuh SIEM

TheHive MCP Server