Claude Desktop supports MCPB (Model Context Protocol Binary) files for easy one-click installation of MCP servers like TheHiveMCP.

Step 1: Install Claude Desktop

Download and install Claude Desktop for your operating system.

Step 2: Download TheHiveMCP MCPB package

Download the appropriate MCPB file for your system from the latest release:

• macOS (Intel): thehivemcp-v0.2.0-darwin-amd64.mcpb
• macOS (Apple Silicon): thehivemcp-v0.2.0-darwin-arm64.mcpb
• Windows (64-bit): thehivemcp-v0.2.0-windows-amd64.mcpb
• Linux (64-bit): thehivemcp-v0.2.0-linux-amd64.mcpb
• Linux (ARM64): thehivemcp-v0.2.0-linux-arm64.mcpb

Step 3: Install the MCPB package

Double-click the downloaded .mcpb file. Claude Desktop automatically:

• Installs TheHiveMCP server
• Prompts you to configure your TheHive connection settings
• Adds TheHiveMCP to your available tools

Step 4: Configure TheHive connection

When prompted during installation, provide:

• TheHive URL: Your TheHive instance URL (for example, https://thehive.company.com)
• API Key: Your TheHive API key for authentication
• Organisation: Your TheHive organisation name (optional, defaults to the user's own organisation)
• Permissions config: (Optional) Choose from:
  • read_only - Default safe mode (search only, no modifications)
  • admin - Full access (for testing/development only)
  • Custom path to your permissions YAML file
• OpenAI API Key: (Optional) For natural language processing fallback when MCP client doesn't support sampling

Step 5: Test your setup

After installation, restart Claude Desktop and look for the 🔧 tools icon. Try asking: "Show me recent high-severity alerts from TheHive" or "What security cases are currently open?"

Step 1: Run TheHiveMCP server

Quick Docker setup

For immediate testing and development:

docker run -d \
  --name thehive-mcp \
  -p 8082:8082 \
  -e THEHIVE_URL=https://your-thehive-instance.com \
  -e THEHIVE_API_KEY=your-api-key-here \
  -e MCP_BIND_HOST=0.0.0.0 \
  -e MCP_PORT=8082 \
  ghcr.io/strangebeecorp/thehivemcp/thehivemcp:latest

Docker Compose (Recommended for teams)

Create docker-compose.yml:

services:
  thehive-mcp:
    image: ghcr.io/strangebeecorp/thehivemcp/thehivemcp:latest
    ports:
      - "8082:8082"
    environment:
      - THEHIVE_URL=${THEHIVE_URL}
      - THEHIVE_API_KEY=${THEHIVE_API_KEY}
      - THEHIVE_ORGANISATION=${THEHIVE_ORGANISATION}
      - MCP_BIND_HOST=0.0.0.0
      - MCP_PORT=8082
      - PERMISSIONS_CONFIG=/app/permissions.yaml
    volumes:
      - ./config/permissions.yaml:/app/permissions.yaml:ro
    restart: unless-stopped

# Start services
docker-compose up -d

Step 2: Configure your MCP client

Point your MCP client to connect to the HTTP server at http://localhost:8082/mcp.

🐳 For advanced Docker setups: See Remote Docker Guide for scalable HTTP deployments with multi-tenant configuration.

Download Pre-built binary

# Download for your platform from releases
curl -L -o thehivemcp https://github.com/StrangeBeeCorp/TheHiveMCP/releases/latest/download/thehivemcp-[platform]-[arch]
chmod +x thehivemcp

Run with Stdio transport

In your MCP host MCP config file (like claude_desktop_settings.json) add the following configuration:

```json
{
  "mcpServers": {
    "thehive": {
      "command": "/path/to/thehivemcp",
      "args": ["--transport", "stdio"],
      "env": {
        "THEHIVE_URL": "https://your-thehive-instance.com",
        "THEHIVE_API_KEY": "your-api-key-here",
        "THEHIVE_ORGANISATION": "your-org-name",
        "PERMISSIONS_CONFIG": "read_only",
        "OPENAI_API_KEY": "your-api-key-here",
        "OPENAI_MODEL": "gpt5"
      }
    }
  }
}

Most MCP hosts don't support Sampling. Check if yours does [here][https://modelcontextprotocol.io/clients].

If it does, you can remove the OpenAI key and model from the config.

Run as HTTP server

# Run HTTP server for web clients
./thehivemcp --transport http \
  --addr "0.0.0.0:8082" \
  --thehive-url "$THEHIVE_URL" \
  --thehive-api-key "$THEHIVE_API_KEY" \
  --thehive-organisation "$THEHIVE_ORGANISATION"

💻 For local MCP host integration: See stdio Local Guide for GitHub Copilot, Claude Desktop, and other local MCP clients.

Embed TheHiveMCP directly into Go applications:

import "github.com/StrangeBeeCorp/TheHiveMCP/bootstrap"

// Use environment credentials
mcpServer := bootstrap.GetMCPServerAndRegisterTools()

// Or use custom credentials with permissions
creds := &bootstrap.TheHiveCredentials{
    URL: "https://thehive.example.com",
    APIKey: "key",
    Organisation: "org",
}
mcpServer := bootstrap.GetInprocessServer(creds, "/path/to/permissions.yaml")
bootstrap.RegisterToolsToMCPServer(mcpServer)

Note: Only the bootstrap package is public API. Internal packages may change without notice.

Configuration parameters

Example configuration

# .env file - Base configuration
THEHIVE_URL=https://thehive.example.com
THEHIVE_API_KEY=<thehive_api_key>
THEHIVE_ORGANISATION=<thehive_organisation>  # Optional, defaults to user's own organisation
PERMISSIONS_CONFIG=docs/examples/permissions/analyst.yaml  # Optional, defaults to read-only
MCP_BIND_HOST=0.0.0.0
MCP_PORT=8082
OPENAI_API_KEY=<openai_api_key>  # Optional, for fallback LLM
LOG_LEVEL=INFO
# Permissions options (choose one):
# PERMISSIONS_CONFIG=read_only                              # Default: safe read-only access
# PERMISSIONS_CONFIG=admin                                  # Full access (development/testing only)
# PERMISSIONS_CONFIG=docs/examples/permissions/analyst.yaml # Custom permissions file

# Optional AI features:
# OPENAI_API_KEY=sk-your-key    # Fallback when client doesn't support sampling

Multi-tenant & Per-Request Configuration

HTTP Headers (HTTP transport only):

curl -X POST http://localhost:8082/mcp \
  -H "Authorization: Bearer different-api-key" \
  -H "X-TheHive-Org: other-org" \
  -H "X-TheHive-Url: https://other-thehive.com" \
  -d '{"method":"initialize",...}'

Built-in Permission Profiles

• read_only (default): Search entities, browse resources only
• admin: Full access to all operations (development/testing only)
• Custom file: Fine-grained permissions via YAML configuration

See docs/permissions.md for detailed permission configuration and examples.

🤖 MCP Sampling (AI-Powered Natural Language)

TheHiveMCP uses MCP Sampling for natural language processing in the search-entities tool to convert queries like "high severity alerts from last week" into TheHive filters.

How it works:

1. Client-side sampling (preferred): Uses the MCP client's built-in AI model
2. Server-side fallback: Uses OpenAI API when client doesn't support sampling
3. Graceful degradation: Without either, natural language search fails but other tools work normally

Current MCP client support:

• ✅ Github Copilot: Full sampling support
• ❌ Most other MCP clients: Limited or no sampling support (including Claude Desktop)
• 🔧 Workaround: Configure OPENAI_API_KEY for server-side processing

# Enable server-side fallback for clients without sampling
export OPENAI_API_KEY=sk-your-openai-key
export OPENAI_BASE_URL=https://api.openai.com/v1  # Or OpenRouter for more models

🛡️ MCP Elicitation (User Confirmation)

TheHiveMCP uses MCP Elicitation to request user confirmation before executing potentially dangerous operations (create, update, delete entities).

How it works:

1. Supported clients: Show confirmation dialog before executing modifications
2. Unsupported clients: Operations proceed automatically (logged with warnings)
3. Security layer: Prevents accidental data modification

Current MCP client support:

• ✅ Github Copilot: Full elicitation support with confirmation dialogs
• ❌ Most other MCP clients: No elicitation support (including Claude Desktop)
• ⚠️ Security note: Use restrictive permissions with clients that don't support elicitation

Example elicitation prompt:

Confirm POST request to TheHive API?

Operation: Create Alert
Entity: {"title": "Security Incident", "severity": 3, ...}

get-resource

Access TheHive resources for documentation, schemas, and metadata. The entry point for exploring TheHive capabilities through a hierarchical URI-based resource system.

Key features:

• Browse resource catalog and categories with flexible navigation
• Access entity schemas (output, create, and update variants for each entity type)
• Query metadata for available options with subcategory support
• Get comprehensive documentation through hierarchical paths

Schema organisation:

• Output schemas: hive://schema/{entity} - Fields returned from queries
• Create schemas: hive://schema/{entity}/create - Required fields for creation
• Update schemas: hive://schema/{entity}/update - Available fields for updates

Navigation examples:

• Browse automation metadata: uri="hive://metadata/automation"
• List entity schemas: uri="hive://schema"
• Get specific alert schema: uri="hive://schema/alert"

search-entities

Search for entities in TheHive using natural language queries. Uses AI to translate natural language into TheHive filters.

Key features:

• Natural language query processing
• Support for all entity types (alerts, cases, tasks, observables)
• Flexible filtering and sorting options
• Custom column and data field selection
• Count-only queries for performance optimization

manage-entities

Perform comprehensive CRUD and workflow operations on TheHive entities with full support for relationships and constraints.

Key features:

• Create, update, delete operations for all entity types
• Comment support for cases and task logs
• Promote alerts to cases
• Merge cases together, merge alerts into cases, deduplicate observables
• Respect for entity hierarchies and relationships
• Batch operations support

execute-automation

Execute Cortex analyzers and responders with comprehensive status monitoring and parameter customization.

Key features:

• Run analyzers on observables for threat intelligence
• Execute responders for automated actions
• Monitor job and action status
• Support for custom parameters and multiple Cortex instances

Development

Dockerized development workflow

All development operations use Docker containers for consistency and isolation:

Core commands:

• make all - Format, security checks, tests, and build
• make build - Build binary using Docker
• make run ARGS="arguments" - Run application with custom arguments
• make test - Run tests with Docker network support for integration tests
• make dev - Development server with hot reload (requires local air)

Quality and security:

• make fmt - Format code using Docker
• make security - Run all security checks (vulncheck, sast, vetlint)
• make sast - Static application security testing
• make vetlint - Linting checks
• make vulncheck - Vulnerability scanning

Docker operations:

• make docker-build - Build production Docker image
• make docker-run - Run production container

Dependencies:

• make updatedep - Update Go dependencies
• make install-dev-deps - Install development tools (Docker-based)

Utilities:

• make clean - Remove build artifacts
• make help - Display all available targets

Architecture: Transport (bootstrap/), Tools (internal/tools/), Resources (internal/resources/), Integration (internal/utils/), Prompts (internal/prompts/)