mcp-server-malcolm

English | 繁體中文

The first MCP server for Malcolm, the open-source network traffic analysis platform (Zeek + Suricata + Arkime + OpenSearch, with optional NetBox).

It gives any MCP-compatible AI agent structured access to Malcolm: search and aggregate network traffic, discover field names, query Suricata alerts, browse Arkime sessions, resolve NetBox assets, and check system health. Turn on the write classes and it can also create alerts, tag sessions, launch hunts, and upload PCAP. It is read-only until you turn one on.

Contents

• Why an MCP layer
• Quick start
  • 1. Install
  • 2. Register it with your client
  • 3. Connection settings
  • 4. Enabling write tools (optional)
  • Other ways to install
• Read-only until you opt in
• Read tools
• Write tools (opt-in)
• Trimming the read surface
• Security model
• Audit
• Python (direct import)
• Malcolm filter syntax
• Examples
• Protocol notes
• Configuration reference
• Verifying against your own Malcolm
• Malcolm API endpoints used
• Non-goals
• License

Why an MCP layer

Malcolm keeps all network metadata in one OpenSearch index (arkime_sessions3-*) with non-standard field names and its own filter syntax. An LLM asked to write raw OpenSearch DSL against that index gets it wrong more often than not. This server takes that job off the model:

• It exposes Malcolm's filter syntax instead of raw DSL.
• It provides field discovery so the model checks field names before it queries.
• It provides value enumeration so the model sees what values a field actually holds.
• It covers both field vocabularies. Arkime expressions take Arkime's own names (ip.src), the rest of Malcolm takes ECS names (source.ip), and Malcolm's own field list carries only the second set. arkime_field_search supplies the first.
• It wraps Suricata alert queries and handles the field mapping (suricata.alert.* vs rule.*).
• It adds NetBox asset context (IP-to-device, network segments).

The failure mode this is built against is a quiet one. Malcolm answers a query against a field it does not index with an empty result rather than an error, so a model that guesses a plausible-but-wrong name reads "no such traffic" and moves on. When a search comes back empty, this server checks the fields the query named and reports the name Malcolm actually stores the value under. That lookup runs only after a result set is already empty, so nothing is added to the model's context on queries that worked.

The write side follows the same idea. Rather than hand an agent the raw OpenSearch and NetBox passthroughs that Malcolm already leaves open to any authenticated user, this server exposes a small, named, audited set of write actions. More on that under Security model.

Quick start

You don't write any code to use this. An MCP client (Claude Code, Claude Desktop, Cursor, …) launches the server as a subprocess and talks to it over stdio; your job is to tell the client how to launch it and which credentials to inject.

Every command in this chapter was run as printed, on Linux/aarch64 (kernel 6.14, Python 3.11.14 and 3.14.6) against a live Malcolm v26.07.1, and the error text is verbatim. The install in §1, its check, and the Claude Code registration in §2 were run a second time on macOS 26/arm64 with Python 3.14.6, against a live Malcolm 25.12.1. Where something was reasoned from source rather than executed, or was left untested (x86_64 hosts, GUI MCP clients, four of the five write classes), it says so at that point.

1. Install

You need Python 3.11 or newer, a Malcolm instance with API access, and an HTTPS route to it.

pip install mcp-server-malcolm      # published release

Check the install by starting the server with stdin closed. It prints its write-class banner, reaches EOF, and exits 0:

$ mcp-server-malcolm < /dev/null
[mcp-server-malcolm] write classes: alerting=off arkime-tag=off hunt-job=off pcap-upload=off arkime-view=off
$ echo $?
0

Nothing has to be configured for the process to start. Connection settings are read at startup but not used until a tool calls Malcolm, so a wrong URL or password surfaces as a failing tool call, not a failed launch.

2. Register it with your client

Claude Code — one command, no config file to find:

claude mcp add malcolm \
  -e MALCOLM_URL=https://malcolm.example \
  -e MALCOLM_USERNAME=analyst \
  -e MALCOLM_PASSWORD='your-password' \
  -e MALCOLM_SSL_VERIFY=/path/to/malcolm-ca.crt \
  -- mcp-server-malcolm

Everything after -- is the launch command; each -e is an environment variable injected into it. claude mcp add --help gives the signature as claude mcp add [options] <name> <commandOrUrl> [args...], with -e, --env <env...> and -s, --scope <scope>.

Registering, health-checking and removing a server, run end to end:

$ claude mcp add malcolm-deploy-test -s local \
    -e MALCOLM_URL=https://malcolm.example \
    -e MALCOLM_USERNAME=analyst \
    -e MALCOLM_PASSWORD='your-password' \
    -e MALCOLM_SSL_VERIFY=false \
    -- /tmp/mcp-malcolm-deploy/venv/bin/mcp-server-malcolm
Added stdio MCP server malcolm-deploy-test with command: … to local config

$ claude mcp list
Checking MCP server health…
malcolm-deploy-test: /tmp/mcp-malcolm-deploy/venv/bin/mcp-server-malcolm  - ✔ Connected

$ claude mcp remove malcolm-deploy-test -s local
Removed MCP server malcolm-deploy-test from local config

Pick where the entry is stored with -s:

The password in that command is a literal, so it goes into your shell history, and for as long as claude mcp add runs it sits in ps where every other process on the host can read it. Read it in first and pass the variable:

read -rs MALCOLM_PASSWORD && export MALCOLM_PASSWORD
claude mcp add malcolm \
  -e MALCOLM_URL=https://malcolm.example \
  -e MALCOLM_USERNAME=analyst \
  -e MALCOLM_PASSWORD="$MALCOLM_PASSWORD" \
  -- mcp-server-malcolm

read -rs keeps the typing off the screen, and the shell records the unexpanded "$MALCOLM_PASSWORD", so history holds the variable name instead of the secret. The ps window during the add itself stays open, the same way docker inspect keeps a container's copy readable. Either route ends with the password in cleartext in ~/.claude.json, mode 0600 on the machine this was checked on, so file permissions are the only thing protecting it there.

claude mcp get malcolm prints the registered command and environment. Note that it prints MALCOLM_PASSWORD in cleartext, unmasked, so don't run it where the terminal is being recorded or shared.

For a project-scope entry, keep the secret in each person's shell rather than in the file:

{
  "mcpServers": {
    "malcolm": {
      "command": "mcp-server-malcolm",
      "env": { "MALCOLM_PASSWORD": "${MALCOLM_PASSWORD}" }
    }
  }
}

Other MCP clients — no equivalent CLI, so edit the client's own JSON config. The block is the same shape:

{
  "mcpServers": {
    "malcolm": {
      "command": "mcp-server-malcolm",
      "env": {
        "MALCOLM_URL": "https://malcolm.example",
        "MALCOLM_USERNAME": "analyst",
        "MALCOLM_PASSWORD": "your-password",
        "MALCOLM_SSL_VERIFY": "/path/to/malcolm-ca.crt"
      }
    }
  }
}

That exact block was verified by driving its command and env fields through the MCP Python SDK's own stdio_client and ClientSession, which is what a generic client does with them. No GUI client was launched here: Claude Desktop reads claude_desktop_config.json and other clients vary, per their own docs, which this project has not independently confirmed.

If mcp-server-malcolm isn't on the PATH your client sees (common with a virtualenv), give the absolute path to the executable instead: /path/to/.venv/bin/mcp-server-malcolm.

3. Connection settings

Defaults below are what MalcolmClient.from_env reads (client.py:294-304).