Atomic Red Team MCP
Enables searching, validating, and executing Atomic Red Team tests via Google AI Studio or Gemini.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Atomic Red Team MCP list atomic tests for T1059.002"
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.
Atomic Red Team MCP Server
An MCP (Model Context Protocol) server that provides access to Atomic Red Team tests.
Available Tools and Resources
The server provides the following MCP tools:
query_atomics- Search atomics by technique ID, name, description, or platformrefresh_atomics- Download latest atomics from GitHubvalidate_atomic- Validate atomic test YAMLget_validation_schema- Get the atomic test schemaexecute_atomic- Execute atomic tests (requiresART_EXECUTION_ENABLED=true)
And resources:
file://documents/{technique_id}- Read atomic test files by technique ID
Usage Examples
"Search mshta atomics for windows"
"Show me all the atomic tests for T1059.002"
"Find all the applescript atomics for macOS"
"Validate this atomic test YAML "
Related MCP server: MITRE ATT&CK MCP Server
Installation
The Atomic Red Team MCP server can be installed in various development tools and AI assistants. Choose your platform below for detailed installation instructions:
Quick Start
Recommended: Using uvx
uvx atomic-red-team-mcpUsing Docker
docker run --rm -i ghcr.io/cyberbuff/atomic-red-team-mcp:latestPlatform-Specific Guides
VSCode - Installation guide for VSCode
Claude Desktop & Claude Code - Installation guide for Anthropic's Claude Desktop app and Claude Code CLI
Cursor - Installation guide for Cursor IDE
Windsurf - Installation guide for Windsurf editor
Google AI Studio / Gemini - Installation guide for Google's AI tools
Other Tools - Cline, Zed, and generic MCP clients
Installation Methods
Each platform supports multiple installation methods:
uvx (Recommended) - Easiest setup, automatic updates
Docker - Isolated environment, consistent across systems
Remote Server ⚠️ - Hosted on Railway (free tier, may have limits)
Configuration
Environment Variables
Check the .env.example file for a list of environment variables and their default values.
Server Configuration
ART_MCP_TRANSPORT- Transport protocol (stdio, sse, streamable-http)ART_MCP_HOST- Server host address (default: 0.0.0.0)ART_MCP_PORT- Server port number (default: 8000)
Repository Configuration
ART_GITHUB_URL- GitHub URL for atomics repository (default: https://github.com)ART_GITHUB_USER- GitHub user/org (default: redcanaryco)ART_GITHUB_REPO- Repository name (default: atomic-red-team)ART_DATA_DIR- Local directory path where atomic test files are stored (default: ./atomics)
Security Configuration
ART_EXECUTION_ENABLED- Enable theexecute_atomictool (default: false). Set totrue,1, oryesto enable. ⚠️ WARNING: Only enable in controlled environments as this allows executing potentially dangerous security tests.Enable Authentication if you are hosting a remote MCP server
Authentication Configuration
ART_AUTH_TOKEN- Static bearer token for authentication (optional, authentication disabled if not set)ART_AUTH_CLIENT_ID- Client identifier for authenticated requests (default: authorized-client)
Enabling Atomic Test Execution
By default, the execute_atomic tool is disabled for safety reasons. To enable it:
# Using uvx
ART_EXECUTION_ENABLED=true uvx atomic-red-team-mcp⚠️ Security Warning: Only enable atomic test execution in controlled, isolated environments (like test VMs or sandboxes). These tests can modify system state, create files, execute commands, and perform actions that may be flagged as malicious by security tools.
Authentication
The server supports static token authentication for securing access to the MCP tools and resources. When enabled, clients must include a bearer token in the Authorization header:
Authorization: Bearer <your-token>To enable authentication:
Set the
ART_AUTH_TOKENenvironment variable:export ART_AUTH_TOKEN="your-secure-token-here"Start the server (authentication is automatically enabled)
Clients authenticate by including the token in requests:
curl -H "Authorization: Bearer your-secure-token-here" http://localhost:8000
Security Notes:
Authentication is disabled by default (no token required)
When
ART_AUTH_TOKENis set, all requests must include a valid bearer tokenUse strong, randomly generated tokens in production
Never commit tokens to version control
For development/testing, use a simple token. For production, use a cryptographically secure token
Example with Docker:
docker run --rm -i \
-e ART_AUTH_TOKEN="my-secure-token" \
-e ART_AUTH_CLIENT_ID="my-client" \
ghcr.io/cyberbuff/atomic-red-team-mcp:latestBuilt With
Available Tools
6 toolsgenerate_atomicARead-only
Generate an atomic test for a MITRE ATT&CK technique using AI assistance.
Uses the MCP client's LLM to draft an atomic test YAML for the given technique and platform, then validates it automatically. If the generated test has errors or warnings, re-samples up to 3 times to fix them before returning.
Args: technique_id: MITRE ATT&CK technique ID (e.g., "T1059.001"). Used to focus the generated test on the correct technique.
platform: Target platform for the test. Valid values: windows, linux, macos.
Defaults to "linux".
description: Optional free-text description of what the test should do or
demonstrate. Leave blank to let the AI determine the best approach
for the technique.Returns: GenerateAtomicOutput: Result containing: - valid (bool): Whether the final test passes schema validation - message (str): Success or error message - atomic_name (str): Name of the generated test (if valid) - supported_platforms (list): Platforms declared in the test (if valid) - yaml (str): Generated YAML content (if valid) - warnings (list): Best-practice warnings to address (if any) - error (str): Validation error details (if invalid)
Notes:
- Requires the MCP client to support server-side sampling
- If the client doesn't support sampling, returns an error
- The generated YAML is validated but NOT saved automatically
- Use server_info to find where to save validated tests
- Always review generated tests before use in production environments
Inputs: technique_id (required), platform, description. Returns: Structured output for generate_atomic tool. Provides validation status alongsid…
get_validation_schemaARead-onlyIdempotent
Get the JSON schema that defines the structure and requirements for atomic tests.
This schema provides the complete specification for creating valid atomic tests. It defines all fields (required and optional), data types, validation rules, and constraints. Use this as a reference when creating or modifying atomic tests to ensure they meet quality standards.
The schema follows the Atomic Red Team YAML format and is automatically generated from the Pydantic models, ensuring it's always in sync with validation rules.
Returns: dict: JSON Schema (Draft 7) containing: - definitions: Nested object definitions (Executor, Dependency, etc.) - properties: Field definitions with types and constraints - required: List of mandatory fields - additionalProperties: Whether extra fields are allowed - field descriptions: Human-readable explanations for each field
Schema Structure: The schema defines these main sections: - name: Test name (required, min 1 character) - description: Test explanation (required, min 1 character) - supported_platforms: Platform list (required, min 1 platform) - executor: Execution method (required, CommandExecutor or ManualExecutor) - input_arguments: Parameterized inputs (optional, dict) - dependencies: Prerequisites (optional, list) - dependency_executor_name: Executor for dependencies (optional) - auto_generated_guid: Unique ID (optional, auto-generated)
Examples: # Get the schema schema = get_validation_schema()
# Check required fields
required_fields = schema['required']
print(f"Required fields: {required_fields}")
# View field definitions
properties = schema['properties']
print(f"Available fields: {list(properties.keys())}")
# Check platform options
platform_enum = schema['definitions']['Platform']['enum']
print(f"Valid platforms: {platform_enum}")Common Use Cases: 1. Creating new tests: Reference required fields and formats 2. Understanding validation: See what rules will be enforced 3. Tool development: Use schema for code generation 4. Documentation: Generate field descriptions automatically
Notes: - Schema is generated from Pydantic models at runtime - Always reflects current validation rules - Includes custom validators and constraints - Follows JSON Schema Draft 7 specification - Can be used with JSON Schema validators in any language - Do not add comments to the created atomic test
Inputs: no named parameters. Returns: object
query_atomicsARead-onlyIdempotent
Search and filter atomic tests across the repository.
This tool searches through all atomic tests and returns matches based on your
criteria. You can search by free-text query, or filter by specific attributes like
technique ID, GUID, or platform. Results are paginated — use the returned
next_cursor to fetch subsequent pages.
Args: query: Free-text search term to match against all atomic test fields including name, description, commands, and input arguments. Supports multi-word queries where all words must match (AND logic). Examples: "powershell registry", "credential access", "T1059"
guid: Filter by exact atomic test GUID (UUID format).
Example: "a8c41029-8d2a-4661-ab83-e5104c1cb667"
Use this when you know the specific test you want to retrieve.
technique_id: Filter by MITRE ATT&CK technique ID. Must follow the format
T#### or T####.### (e.g., T1059, T1059.001).
Example: "T1059.001" for PowerShell technique
Returns all atomic tests associated with this technique.
technique_name: Filter by technique name (case-insensitive partial match).
Example: "Command and Scripting Interpreter"
Useful when you know the technique name but not the ID.
supported_platforms: Filter by platform (case-insensitive partial match).
Valid platforms: windows, linux, macos, office-365, azure-ad,
google-workspace, saas, iaas, containers, iaas:aws, iaas:azure,
iaas:gcp, esxi
Example: "windows", "linux", "macos"
cursor: Opaque pagination cursor returned by a previous call as `next_cursor`.
Omit or pass null to start from the first page.
limit: Maximum number of results to return per page (1–200, default 50).Returns: QueryAtomicsOutput: Structured output containing: - total_results: Total number of matching atomic tests - atomics: List of matching atomic tests for this page - next_cursor: Opaque cursor for the next page, or null if last page - query_metadata: Information about applied filters
Raises: ValueError: If query is empty without any filters ValueError: If query exceeds 1000 characters ValueError: If technique_id format is invalid (must be T#### or T####.###) ValueError: If limit is outside the range 1–200 ValueError: If cursor is malformed
Inputs: query (required), guid, limit, cursor, +3 more. Returns: Structured output for query_atomics tool. Provides pagination metadata and clea…
refresh_atomicsAIdempotent
Download and reload atomic tests from the GitHub repository.
This tool forces a fresh download of all atomic tests from the configured GitHub repository, replacing any existing local copies. It then reloads all tests into memory, making them immediately available for querying and execution.
Use this tool when:
You want to get the latest atomic tests from the repository
Custom atomic tests were added to the data directory
The atomic test database needs to be refreshed
You suspect the loaded tests are out of sync with the repository
Args: ctx: MCP context (provided automatically by the framework) progress: Background task progress reporter (injected automatically)
Returns: RefreshAtomicsOutput: Structured output containing: - success (bool): Whether the refresh operation completed successfully - message (str): Human-readable message about the refresh operation - atomics_count (int): Number of atomic tests loaded after refresh - repository_url (str): GitHub repository URL that was used for refresh
Process: 1. Deletes existing atomic tests directory (if present) 2. Clones the GitHub repository (configured via ART_GITHUB_* settings) 3. Extracts the atomics directory from the repository 4. Parses all YAML files and validates them 5. Loads atomic tests into server memory 6. Makes tests immediately available to other tools
Configuration: The repository location is controlled by environment variables: - ART_GITHUB_URL: Base GitHub URL (default: https://github.com) - ART_GITHUB_USER: User/organization (default: redcanaryco) - ART_GITHUB_REPO: Repository name (default: atomic-red-team) - ART_DATA_DIR: Local storage path (default: ./atomics)
Examples: # Refresh from default repository refresh_atomics(ctx)
# After setting custom repo in .env:
# ART_GITHUB_USER=your-org
# ART_GITHUB_REPO=custom-atomics
refresh_atomics(ctx)Notes: - This operation may take 30-60 seconds depending on network speed - Runs as a background task — the client receives a task ID immediately and can poll for completion - Requires internet connectivity to GitHub - Overwrites any local modifications to atomic tests - The repository is cloned with depth=1 for efficiency (only latest commit) - Failed YAML files are logged but don't stop the overall refresh
Inputs: no named parameters. Returns: Structured output for refresh_atomics tool. Provides details about the refresh…
server_infoARead-onlyIdempotent
Get comprehensive information about the MCP server configuration and environment.
This tool returns server metadata including version, transport protocol, operating system, and data directory location. Use this to:
Verify server configuration
Check server version for compatibility
Confirm the platform before executing atomic tests
Locate the atomic tests data directory
Args: ctx: MCP context (provided automatically by the framework)
Returns: ServerInfoOutput: Server information with the following fields: - name (str): Server name - always "Atomic Red Team MCP" - version (str): Installed package version (e.g., "1.2.3") Shows "dev" if running from source without installation - transport (str): MCP transport protocol being used Values: "stdio" (default), "sse", or "streamable-http" - os (str): Operating system platform Values: "Darwin" (macOS), "Linux", "Windows" Use this to verify test compatibility before execution - data_directory (str): Absolute path to atomic tests storage directory This is where atomic YAML files are stored Use this path when creating new atomic tests - execution_enabled (bool): Whether atomic test execution is enabled on this server
Examples: # Get server information info = server_info(ctx) print(f"Running version {info.version} on {info.os}")
# Check if remote server for execution
if info.transport == 'streamable-http':
print("This is a remote MCP server")
# Get data directory for creating tests
data_dir = info.data_directory
print(f"Create new tests in: {data_dir}/T####/T####.yaml")Use Cases: 1. Before executing tests: Check OS matches supported_platforms 2. Creating atomic tests: Use data_directory to know where to save files 3. Debugging: Verify configuration settings 4. Version compatibility: Ensure tools match server version
Notes: - This tool always succeeds and never raises exceptions - Information reflects the current runtime configuration - Transport and data_directory come from Settings (environment variables/.env) - OS is detected at runtime and cannot be changed
Inputs: no named parameters. Returns: Structured output for server_info tool. Provides comprehensive server metadata…
validate_atomicARead-onlyIdempotent
Validate an atomic test YAML string against the official Atomic Red Team schema.
This tool checks if your atomic test follows the correct structure and includes all required fields. Use this before finalizing any atomic test to ensure it meets the quality standards and can be properly parsed by Atomic Red Team tools.
The validator performs two levels of checks:
Structural validation: Ensures all required fields are present and properly typed
Best practice warnings: Flags common issues that should be addressed
Args: yaml_string: The complete YAML string of the atomic test to validate. Should include all fields like name, description, supported_platforms, executor, etc. as defined in the schema.
Returns: ValidationOutput: Structured validation result containing: - valid (bool): Whether the atomic test passes validation - message (str): Human-readable success/error message with warnings prominently displayed - atomic_name (str): Name of the atomic test (only if valid) - supported_platforms (list): Platforms the test supports (only if valid) - warnings (list): List of warning messages for best practice violations (only if present) - error (str): Detailed error message (only if invalid)
Validation Warnings: The tool will flag these common issues with ⚠️ warnings: - Presence of 'auto_generated_guid' field (should be auto-generated, not manually set) - Use of echo/print/Write-Host commands (discouraged in test commands)
Warnings do not cause validation to fail, but should be addressed before finalizing.Examples: # Valid atomic test yaml_str = ''' name: Test PowerShell Execution description: Execute a PowerShell command supported_platforms: - windows executor: name: powershell command: Get-Process ''' result = validate_atomic(yaml_str, ctx) # result.valid == True, result.message contains success message
# Test with warnings (still valid but needs improvement)
yaml_str = '''
name: Test with Echo
description: Test with echo command
supported_platforms:
- linux
executor:
name: bash
command: echo "Hello World"
'''
result = validate_atomic(yaml_str, ctx)
# result.valid == True, result.warnings contains warning messages
# Invalid atomic test (missing required field)
yaml_str = '''
name: Incomplete Test
description: Missing supported_platforms
executor:
name: bash
command: ls
'''
result = validate_atomic(yaml_str, ctx)
# result.valid == False, result.error contains error messageRaises: No exceptions are raised - all errors are returned in the ValidationOutput model.
Notes: - Always check the 'valid' field before using the atomic test - Address all warnings even if validation succeeds - Warnings are displayed with ⚠️ emoji for visibility - The 'message' field contains formatted text with warnings prominently shown
Inputs: yaml_string (required). Returns: Structured output for validate_atomic tool. Provides clear validation status wi…
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: server_info for configuration, refresh_atomics for downloading updates, query_atomics for searching, get_validation_schema for schema reference, validate_atomic for checking validity, and generate_atomic for AI-assisted creation. There is no ambiguity or overlap among the tools.
All tool names follow a consistent snake_case verb_noun pattern (e.g., refresh_atomics, query_atomics, validate_atomic). The naming is predictable and uniform, making it easy to infer tool behavior from the name.
Six tools is well-scoped for an Atomic Red Team server. Each tool covers a distinct aspect of the atomic test lifecycle (configuration, refresh, query, schema, validation, generation) without redundancy or bloat.
The tool set covers the core workflows: querying, validating, generating, and updating atomic tests. Minor gaps include lack of direct create/update/delete tools for saving tests to disk and no execution tool, but server_info provides the data directory path and the generation flow supports creating tests.
Maintenance
Related MCP Connectors
Free AI test helpers: injection inputs, OWASP mapping, release plans, response and tool-call packs.
Ask about your Kodem Security data and act on findings in plain language, with your permissions.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Create, run and debug Leapwork Play tests and runlists, build knowledge bases, and use AI workflows.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables querying the MITRE ATT\&CK framework for adversarial tactics, techniques, mitigations, and detection methods through natural language, supporting both ID-based and fuzzy name-based searches.3-
- AlicenseAqualityBmaintenanceEnables AI-native access to the MITRE ATT\&CK framework, allowing LLMs and agents to query techniques, threat groups, software, and generate ATT\&CK Navigator layers for threat intelligence and security workflows.65573 npm5Apache 2.0
- FlicenseNot gradedqualityDmaintenanceProvides search, detail lookup, and gap listing tools for a security control inventory, enabling natural language queries about control status and gaps.-
- AlicenseNot gradedqualityCmaintenanceEnables querying MITRE ATLAS adversarial AI threat intelligence, including techniques, tactics, and case studies, through natural language.44 PyPIMIT