AssemblyLine 4 MCP Server

AssemblyLine 4 MCP Server

MCP server for the AssemblyLine 4 malware analysis platform.

Setup

npm install
npm run build

Copy .env.example to .env and fill in your credentials:

AL4_URL=https://your-al4-instance:443
AL4_USERNAME=your_username
AL4_APIKEY=keyname:your_api_key_password

API keys are created in AssemblyLine under Account → Security → Manage API Keys.

Running

AL4_URL=... AL4_USERNAME=... AL4_APIKEY=... node dist/src/index.js

Claude Code integration

Add to your ~/.claude/claude_desktop_config.json (or project .claude/settings.json):

{
  "mcpServers": {
    "assemblyline4": {
      "command": "node",
      "args": ["/absolute/path/to/vibe-assemblylinev4-mcp/dist/src/index.js"],
      "env": {
        "AL4_URL": "https://your-al4-instance:443",
        "AL4_USERNAME": "your_username",
        "AL4_APIKEY": "keyname:password"
      }
    }
  }
}

Self-signed / dev certificates

Set AL4_TLS_VERIFY=false in the env block to skip TLS verification.

Available tools

Testing & CI

Two layers of tests live under test/:

• test/integration.ts — drives AL4Client and the MCP server end-to-endagainst an in-process mock of the AL4 REST API (test/mock-al4.ts).Fast, hermetic, runs on every push/PR via .github/workflows/ci.yml.

  npm test
  

• test/e2e.ts — drives AL4Client against a real Assemblyline 4appliance. The .github/workflows/e2e.yml workflow spins up the upstreamassemblyline-docker-composeappliance (core stack only — Elasticsearch, Redis, MinIO, AL core/UI/nginx;service images are skipped to fit the runner's disk quota), bootstraps theadmin user, mints an API key, and runs the suite. Because submissions arenot blocked on services, they complete with an empty result tree — enoughto validate every API the MCP server exposes.

  The e2e workflow runs:

  • nightly (05:27 UTC),
  • on workflow_dispatch,
  • on PRs labelled run-e2e.

  To reproduce locally:

  bash scripts/ci/start-al4.sh
  APIKEY=$(AL4_URL=https://localhost AL4_ADMIN_USER=admin AL4_ADMIN_PASSWORD=admin \
           bash scripts/ci/create-apikey.sh)
  AL4_URL=https://localhost AL4_USERNAME=admin AL4_APIKEY=$APIKEY \
    AL4_TLS_VERIFY=false node dist/test/e2e.js
  

Running CI locally

Two equivalent paths, depending on what you want to validate:

1. The fast workflow, exactly as GitHub Actions runs it — viaact:

   # one-time: install act (https://nektosact.com/installation/)
   npm run ci:local            # runs .github/workflows/ci.yml in Docker
   

   act reads .actrc, which pins the catthehacker ubuntu:act-latestimage (has Node, git, curl, etc.). This is the cleanest way to catchregressions in the workflow YAML itself.

2. The e2e workflow — act is not recommended here because the jobspins up its own docker-compose stack, and docker-in-docker via actmakes networking and disk usage painful. Use the wrapper scriptinstead, which runs the same steps directly on your host:

   npm run e2e:local           # build → start appliance → mint key → run e2e → teardown
   KEEP_RUNNING=1 npm run e2e:local   # leave appliance up afterwards for poking
   SKIP_BUILD=1   npm run e2e:local   # skip npm ci + tsc, reuse dist/
   

   Or break it apart:

   npm run e2e:up              # just bring up the appliance
   APIKEY=$(npm run --silent e2e:apikey)
   AL4_URL=https://localhost AL4_USERNAME=admin AL4_APIKEY=$APIKEY \
     AL4_TLS_VERIFY=false npm run test:e2e
   

   Requirements: Linux host (or WSL2 / macOS), docker + compose plugin,node 20+, ~15 GB free disk. Windows users: run the scripts from insideWSL — the appliance won't come up under Git Bash because of howdocker-compose paths and openssl interact on native Windows.