nagameTW/mcp-server-malcolm

**English** | 繁體中文
Ask an AI agent about the traffic in your Malcolm instance, and it queries Malcolm with the field names and filter syntax Malcolm actually uses instead of guessing them. For example:
- "Show every Suricata alert involving 192.0.2.15 in the last 24 hours, and which NetBox device owns that IP." → malcolm_alerts, malcolm_netbox_lookup
- "Who were the top talkers by protocol over the last hour?" → malcolm_aggregate
- "List the executables Zeek carved out of yesterday's traffic, with their hashes." → malcolm_file_scans
- "Upload this PCAP, then hunt the stored packets for this string." → malcolm_upload_pcap, arkime_create_hunt (write tools, off by default)
**Read-only by default.** The write tools that create alerts, tag sessions, launch hunts or upload PCAP are not registered until you turn on their write class. See Read-only until you opt in.
*An unedited Claude Code session against Malcolm's public training instance (training.malcolm.fyi): two malcolm_aggregate calls, then the answer. Claude Code ran in --verbose mode so each tool call is shown; by default it folds them into one "Calling malcolm" line.*
mcp-server-malcolm is an MCP server for Malcolm, the open-source network traffic analysis platform (Zeek + Suricata + Arkime + OpenSearch, with optional NetBox). It runs under any MCP client, such as Claude Code, Claude Desktop or Cursor.
Contents
- Quick start
- 1. Install
- 2. Register it with your client
- 3. Connection settings
- 4. Enabling write tools (optional)
- Other ways to install
- Why an MCP layer
- 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
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.
Where this README was tested lists which commands in this chapter were run as printed for this revision, and on what platform. Error text quoted from those runs is verbatim.
1. Install
You need Python 3.11 or newer, a Malcolm instance with API access, and an HTTPS route to it.
Check the install by starting the server with stdin closed. It prints its write-class banner, reaches EOF, and exits 0:
bash
$ 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
bash
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
json
{
"mcpServers": {
"malcolm": {
"command": "mcp-server-malcolm",
"env": { "MALCOLM_PASSWORD": "${MALCOLM_PASSWORD}" }
}
}
}
json
{
"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"
}
}
}
}
Error executing tool malcolm_ping: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1082)
Error executing tool malcolm_ping: Client error '401 Unauthorized' for url 'https://malcolm.example/mapi/ping'
For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
Error executing tool malcolm_ping: ConnectTimeout for https://192.0.2.99:9999/mapi/ping