Kolide MCP Server

Model Context Protocol server for Kolide API integration. Provides complete access to Kolide's device management and security monitoring platform with enhanced Live Query capabilities, caching, and resilience patterns.

Latest: v0.11.0 - Toolhost Pattern implementation reduces context overhead by ~90% while maintaining 100% backward compatibility!

Features

• 🎯 Toolhost Pattern Architecture - 5 intelligent dispatchers replacing 58 individual tools
• 🚀 Enhanced Live Query Experience - Simplified workflow with auto-publishing and status tracking
• 💾 Intelligent Caching - Reduces API calls and improves response times
• 🔄 Automatic Retries - Exponential backoff with jitter for transient failures
• 🛡️ Circuit Breaker - Protects against cascading failures
• 📊 Built-in Telemetry - Track usage, performance, and errors
• ✅ Query Validation - Validate osquery syntax before execution
• 📚 Query Templates - Pre-built queries for common use cases
• 🔍 Full Transparency - Complete operation discovery with MCP compliance

Installation

npm install -g kolide-mcp-server

Configuration

Required environment variable:

export KOLIDE_API_KEY="your-api-key"

Optional:

export KOLIDE_API_VERSION="2023-05-26"
export KOLIDE_BASE_URL="https://api.kolide.com"

Usage

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "kolide": {
      "command": "npx",
      "args": ["kolide-mcp-server"],
      "env": {
        "KOLIDE_API_KEY": "your-api-key"
      }
    }
  }
}

Command Line

npx kolide-mcp-server

Toolhost Architecture (v0.11.0+)

The Kolide MCP Server now uses an intelligent Toolhost Pattern that consolidates operations into 5 category-based dispatchers, reducing context overhead by ~90% while maintaining full backward compatibility.

Category Dispatchers

1. Device Management (device.dispatch) - 13 operations
   • Device CRUD, refresh checks, authentication modes
   • Issues tracking and check results
2. Identity & Access (identity.dispatch) - 13 operations
   • People management, device assignments
   • Person and device groups
3. Compliance & Security (compliance.dispatch) - 13 operations
   • Security checks and configurations
   • Exemption and registration requests
4. Query & Analytics (query.dispatch) - 17 operations
   • Live queries with auto-publishing
   • Reporting tables and saved queries
5. System Administration (admin.dispatch) - 7 operations
   • Audit and authentication logs
   • Admin users and current user info

Using Toolhost Dispatchers

// Example: Get all devices using toolhost
{
  "tool": "device.dispatch",
  "arguments": {
    "operation": "list",
    "cursor": "optional_cursor",
    "per_page": 100
  }
}

// Example: Execute a live query
{
  "tool": "query.dispatch", 
  "arguments": {
    "operation": "execute",
    "query": "SELECT * FROM os_version",
    "target": "all_macs",
    "wait_for_results": true
  }
}

Available Tools (Legacy)

All 58 original tools remain available for backward compatibility:

Audit & Auth (4)

• get_audit_logs - Get audit logs
• get_audit_log - Get audit log by ID
• get_auth_logs - Get authentication logs
• get_auth_log - Get authentication log by ID

Devices (14)

• get_devices - Get all devices
• get_device - Get device by ID
• delete_device - Permanently delete device
• delete_device_registration - Delete device registration
• refresh_device_checks - Refresh checks on device
• update_device_auth_mode - Update authentication mode
• get_device_issues - Get open issues for device
• get_device_check_results - Get check results for device
• search_devices - Search devices with query syntax

People (8)

• get_people - Get all people
• get_person - Get person by ID
• get_deprovisioned_people - Get deprovisioned people
• get_person_devices - Get devices for person
• get_person_issues - Get issues for person
• search_people - Search people with query syntax
• whoami - Get current authenticated user

Groups (7)

• get_device_groups - Get device groups
• get_device_group - Get device group by ID
• get_device_group_devices - Get devices in group
• add_device_to_group - Add device to group
• remove_device_from_group - Remove device from group
• get_person_groups - Get person groups
• get_person_group - Get person group by ID

Checks (6)

• get_checks - Get all checks
• get_check - Get check by ID
• get_check_results - Get check results
• get_check_configuration - Get check configuration
• update_check_configuration - Update check configuration
• search_checks - Search checks with query syntax

Issues (2)

• get_issues - Get all issues
• get_issue - Get issue by ID

Packages (2)

• get_packages - Get all packages
• get_package - Get package by ID

Exemption Requests (4)

• get_exemption_requests - Get exemption requests
• get_exemption_request - Get exemption request by ID
• approve_exemption_request - Approve exemption request
• deny_exemption_request - Deny exemption request

Registration Requests (3)

• get_registration_requests - Get registration requests
• get_registration_request - Get registration request by ID
• update_registration_request - Update registration status

Live Query (7)

• get_live_query_campaigns - Get all campaigns
• get_live_query_campaign - Get campaign by ID
• create_live_query - Create new query campaign
• update_live_query - Update existing campaign
• delete_live_query - Delete campaign
• get_live_query_results - Get query results
• publish_live_query - Publish campaign for execution

Reporting (6)

• get_reporting_tables - Get reporting tables
• get_reporting_table - Get table by name
• get_reporting_queries - Get reporting queries
• get_reporting_query - Get query by ID
• get_table_records - Get records from table
• get_query_results - Get results from query

Admin Users (2)

• get_admin_users - Get admin users
• get_admin_user - Get admin user by ID

Live Query Examples

Basic Usage

Create and run osquery on devices:

// Simple query with auto-publish (NEW!)
{
  "tool": "create_live_query",
  "arguments": {
    "query": "SELECT name, version FROM os_version",
    "name": "OS Version Check",
    "target_macs": true
  }
}

// Get results
{
  "tool": "get_live_query_results",
  "arguments": {
    "campaign_id": "12345",
    "per_page": 100
  }
}

Common Query Templates

The server includes pre-built query templates for common operations:

// Security audit - find listening ports
{
  "tool": "create_live_query",
  "arguments": {
    "query": "SELECT DISTINCT p.name, l.port, l.protocol FROM processes p JOIN listening_ports l ON p.pid = l.pid WHERE l.port < 1024",
    "name": "Privileged Port Audit",
    "target_macs": true
  }
}

// Application inventory
{
  "tool": "create_live_query",
  "arguments": {
    "query": "SELECT name, version, bundle_identifier FROM apps WHERE name IN ('Google Chrome', 'Firefox', 'Safari', 'Microsoft Edge')",
    "name": "Browser Inventory",
    "target_macs": true
  }
}

// Find suspicious processes
{
  "tool": "create_live_query",
  "arguments": {
    "query": "SELECT * FROM processes WHERE on_disk = 0",
    "name": "Memory-only Processes",
    "target_macs": true
  }
}

// USB device monitoring
{
  "tool": "create_live_query",
  "arguments": {
    "query": "SELECT * FROM usb_devices WHERE removable = 1",
    "name": "Removable USB Devices",
    "target_macs": true
  }
}

Advanced Live Query Features

Query Validation

Queries are automatically validated for dangerous operations and syntax errors:

• Prevents DROP, DELETE, TRUNCATE, ALTER operations
• Warns about SELECT * on large tables
• Estimates query complexity

Automatic Retries

Failed API calls are automatically retried with exponential backoff:

• Default: 3 retries with 1s, 2s, 4s delays
• Adds jitter to prevent thundering herd

Caching

Results are intelligently cached to reduce API calls:

• Campaign status: 5 second cache
• Query results: 5 second cache
• Device/person data: 60 second cache

Circuit Breaker

Protects against API failures:

• Opens after 5 consecutive failures
• Half-open state for gradual recovery
• 60 second reset timeout

Search Syntax

Kolide query syntax for search tools:

• name~Chrome - Partial match
• device_type:Mac - Exact match
• serial:ABC123 - Serial number
• will_block_at:[2024-01-01,2024-12-31] - Date range

Pagination

Most list endpoints support pagination:

{
  "cursor": "next_page_cursor",
  "per_page": 100  // Max 100
}

Error Handling

All errors include descriptive messages. Common errors:

• 401: Invalid API key
• 404: Resource not found
• 422: Invalid parameters
• 429: Rate limit exceeded

Development

git clone https://github.com/CoreWeave-Sandbox/kolide-mcp-server
cd kolide-mcp-server
npm install
npm run build

Testing

npm test

TypeScript

Project uses TypeScript with ES2022 target and Node16 module resolution.

Version

Current: 0.11.0 (Toolhost Pattern - 90% context reduction)

License

MIT