Joe Sandbox MCP Server

How to use

Submit analyses from your MCP client by pointing the server at files, URLs, or commands you want sandboxed. You can choose to wait for results or trigger asynchronous submissions and check back later. You will receive structured results, including IoCs, signature detections, process trees, and full PCAPs, all tailored for clean consumption by language models.

How to install

Prerequisites: you need Python and the uv tool available in your environment.

Install and run the MCP server using the provided configuration and environment variables.

# Step 1: Prepare your workspace
# Ensure you have uv installed and available in your PATH

# Step 2: Install dependencies for the MCP server project
uv venv
uv pip install -e .

# Step 3: Run the MCP server using the configuration shown below
# Replace /absolute/path/to/joesandboxMCP with your actual path

Configuration and deployment

You can configure the MCP server to run with uv as a local process. The following example shows how to start the server using uv, with the working directory and main Python entry point specified, and with the required environment variables.

{
  "mcpServers": [
    {
      "name": "joesandbox",
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/joesandboxMCP",
        "run",
        "main.py"
      ],
      "env": [
        {"name": "JBXAPIKEY", "value": "your-jbxcloud-apikey"},
        {"name": "ACCEPTTAC", "value": "SET_TRUE_IF_YOU_ACCEPT"}
      ]
    }
  ]
}

Security and usage notes

This integration relies on your Joe Sandbox Cloud terms and conditions. By setting the environment variable ACCEPTTAC to a truthy value, you acknowledge that you have read and accepted the terms.

Tools and capabilities overview

The MCP server exposes a comprehensive set of tools to analyze and extract threat intelligence from sandbox runs. You can submit analyses, search past analyses, check submission status, obtain AI-derived summaries, and retrieve network indicators, behavioral detections, process trees, unpacked binaries, PCAPs, recent activity, memory dumps, and dropped files.

Troubleshooting and notes

If you encounter issues starting the MCP server, verify that the uv runtime is available, the path to your project directory is correct, and that the API key and TAC acceptance values are provided as shown in the configuration. Ensure that the main.py entry point exists and is accessible from the specified directory.

Submit Analysis

Submit files, URLs, websites, or command lines for sandbox analysis and choose whether to wait for results or return immediately.

Search Past Analyses

Look up historical submissions using hashes, filenames, detection status, threat names, and more.

Check Submission Status

Get the current status and key metadata for a previously submitted sample, including verdicts and analysis score.

AI Summaries

Retrieve high-level reasoning statements generated by the sandbox's AI for easy understanding.

Malicious Dropped Files

See which files were dropped during execution and marked as malicious, with hashes and origins.

Network Indicators

Display domains, IPs, or URLs contacted during analysis with context and evidence.

Behavioral Detections

Get a summary of key behavioral detections triggered during execution.

Process Tree

Visualize the full hierarchy of processes with parent-child relationships and command lines.

Unpacked Binaries

Retrieve binaries that were unpacked or decrypted in memory.

Network Traffic PCAP

Download the full network packet capture recorded during analysis.

Memory Dumps

Retrieve raw memory dumps captured during runtime.

Dropped Files

Retrieve all files dropped during analysis.