How do I use Huntress SAT MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Huntress SAT MCP Server show me the results of the most recent phishing campaign" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Huntress SAT MCP Server

A Model Context Protocol (MCP) server for the Huntress SAT (formerly Curricula) Security Awareness Training API.

Features

Full API Coverage: Tools for managing organizations, learners, phishing campaigns, training courses, assignments, and reports
OAuth2 Authentication: Secure client credentials flow for API access
RBAC Support: Role-based access control (disabled by default, easily enabled)
Multiple Transports: Supports both stdio and streamable-http transports
Docker Ready: Production-ready Docker container with multi-transport support

Installation

From Source

# Clone the repository
git clone https://github.com/example/huntress-sat-mcp.git
cd huntress-sat-mcp

# Install with pip
pip install -e .

# Or with uv (recommended)
uv pip install -e .

Using Docker

# Build the image
docker build -t huntress-sat-mcp .

# Or use docker-compose
docker-compose build

Configuration

The server is configured via environment variables. All variables are prefixed with HUNTRESS_SAT_.

Required Variables

Variable	Description
`HUNTRESS_SAT_CLIENT_ID`	OAuth2 Client ID from Huntress SAT
`HUNTRESS_SAT_CLIENT_SECRET`	OAuth2 Client Secret from Huntress SAT

Optional Variables

Variable	Default	Description
`HUNTRESS_SAT_API_BASE_URL`	`https://api.curricula.com/api/v1`	API base URL
`HUNTRESS_SAT_TOKEN_URL`	`https://api.curricula.com/oauth/token`	OAuth2 token endpoint
`HUNTRESS_SAT_TRANSPORT`	`stdio`	Transport mode: `stdio` or `streamable-http`
`HUNTRESS_SAT_HOST`	`127.0.0.1`	Host for HTTP transport
`HUNTRESS_SAT_PORT`	`8000`	Port for HTTP transport
`HUNTRESS_SAT_RBAC_ENABLED`	`false`	Enable role-based access control
`HUNTRESS_SAT_RBAC_DEFAULT_ROLE`	`viewer`	Default RBAC role
`HUNTRESS_SAT_REQUEST_TIMEOUT`	`30.0`	Request timeout in seconds
`HUNTRESS_SAT_MAX_RETRIES`	`3`	Max retry attempts

Environment File

Create a .env file in the project root:

HUNTRESS_SAT_CLIENT_ID=your_client_id
HUNTRESS_SAT_CLIENT_SECRET=your_client_secret
HUNTRESS_SAT_RBAC_ENABLED=false

Usage

Running with stdio Transport

# Direct execution
huntress-sat-mcp

# Or with Python
python -m huntress_sat_mcp.server

# With environment variables
HUNTRESS_SAT_CLIENT_ID=xxx HUNTRESS_SAT_CLIENT_SECRET=yyy huntress-sat-mcp

Running with Streamable HTTP Transport

# Set transport mode
export HUNTRESS_SAT_TRANSPORT=streamable-http
export HUNTRESS_SAT_HOST=0.0.0.0
export HUNTRESS_SAT_PORT=8000

huntress-sat-mcp

Using Docker

# HTTP Transport (default in docker-compose)
docker-compose up huntress-sat-mcp-http

# Stdio Transport
docker-compose --profile stdio up huntress-sat-mcp-stdio

# Development mode with RBAC enabled
docker-compose --profile dev up huntress-sat-mcp-dev

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "huntress-sat": {
      "command": "huntress-sat-mcp",
      "env": {
        "HUNTRESS_SAT_CLIENT_ID": "your_client_id",
        "HUNTRESS_SAT_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

For HTTP transport:

{
  "mcpServers": {
    "huntress-sat": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

For Docker Compose (stdio transport):

{
  "mcpServers": {
    "huntress-sat": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/path/to/docker-compose.yml",
        "run", "--rm", "-i",
        "huntress-sat-mcp-stdio"
      ]
    }
  }
}

Note: Replace /path/to/docker-compose.yml with the absolute path to your docker-compose.yml file. The -i flag is required for interactive stdin communication with the MCP server. Credentials are loaded from the .env file in the project directory.

Available Tools

Organization Management

Tool	Description
`list_organizations`	List all organizations with pagination and search
`get_organization`	Get details of a specific organization

Learner Management

Tool	Description
`list_learners`	List learners with filters (org, department, tag, status)
`get_learner`	Get learner details
`create_learner`	Create a new learner
`update_learner`	Update learner information
`delete_learner`	Delete a learner

Phishing Campaigns

Tool	Description
`list_phishing_campaigns`	List campaigns with filters and sorting
`get_phishing_campaign`	Get campaign details and metrics
`get_phishing_results`	Get individual learner results for a campaign
`list_phishing_templates`	List available phishing templates

Training

Tool	Description
`list_training_courses`	List available training courses
`get_training_course`	Get course details
`list_assignments`	List training assignments
`get_assignment`	Get assignment details
`create_assignment`	Create a new training assignment

Reports

Tool	Description
`get_learner_progress`	Get training progress for learners
`get_report_summary`	Get summary statistics and metrics

Organization Structure

Tool	Description
`list_departments`	List departments with learner counts
`list_tags`	List tags with learner counts

RBAC

Tool	Description
`get_rbac_status`	Get current RBAC configuration and permissions

Role-Based Access Control (RBAC)

RBAC is disabled by default. When enabled, access to tools is restricted based on user roles.

Available Roles

Role	Description
`admin`	Full access to all tools
`manager`	Can read and write, but cannot delete learners
`analyst`	Can read all data and generate reports
`viewer`	Read-only access to all data

Permissions

org:read, org:write - Organization management
learner:read, learner:write, learner:delete - Learner management
phishing:read, phishing:write - Phishing campaign access
training:read, training:write - Training course access
assignment:read, assignment:write - Assignment management
report:read, report:generate - Report access

Enabling RBAC

export HUNTRESS_SAT_RBAC_ENABLED=true
export HUNTRESS_SAT_RBAC_DEFAULT_ROLE=viewer

Development

Setup

# Install development dependencies
pip install -e ".[dev]"

# Run linting
ruff check src/

# Run type checking
mypy src/

# Run tests
pytest

Project Structure

huntress-sat-mcp/
├── src/
│   └── huntress_sat_mcp/
│       ├── __init__.py      # Package initialization
│       ├── config.py        # Configuration management
│       ├── models.py        # Pydantic models
│       ├── client.py        # API client with OAuth2
│       ├── rbac.py          # Role-based access control
│       └── server.py        # MCP server with tools
├── Dockerfile               # Multi-stage Docker build
├── docker-compose.yml       # Docker Compose configurations
├── pyproject.toml           # Project configuration
└── README.md

API Reference

This MCP server wraps the Huntress SAT (Curricula) API. For detailed API documentation, visit:

License

MIT License

Huntress SAT MCP Server

Huntress SAT MCP Server

Features

Installation

From Source

Using Docker

Configuration

Required Variables

Optional Variables

Environment File

Usage

Running with stdio Transport

Running with Streamable HTTP Transport

Using Docker

MCP Client Configuration

Available Tools

Organization Management

Learner Management

Phishing Campaigns

Training

Reports

Organization Structure

RBAC

Role-Based Access Control (RBAC)

Available Roles

Permissions

Enabling RBAC

Development

Setup

Project Structure

API Reference

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API