mcp-server-malcolm

Malcolm MCP Server 可让 AI Agent 针对 Malcolm 实例中的流量提出问题。该服务使用 Malcolm 所用的字段名称和筛选语法，Agent 无需猜测。它适用于任何 MCP 客户端，例如 Claude Code、Claude Desktop 或 Cursor。

示例请求及其对应的工具：

• “显示过去 24 小时内涉及 192.0.2.15 的所有 Suricata 警报，以及哪个 NetBox 设备拥有该 IP。”这会调用 malcolm_alerts 和 malcolm_netbox_lookup。
• “过去一小时按协议统计的通信量最高的对象是谁？”这会调用 malcolm_aggregate。
• “列出 Zeek 从昨天的流量中提取的可执行文件及其哈希值。”这会调用 malcolm_file_scans。
• “上传此 PCAP，然后在已存储的数据包中搜索此字符串。”这会调用 malcolm_upload_pcap 和 arkime_create_hunt。两者都是写入工具，默认关闭。

录制的会话展示了 Agent 如何回答有关 Modbus 警报的问题。

要求

• Python 3.11 或更高版本。
• 可通过 HTTPS 访问 API 的 Malcolm 实例。
• MCP 客户端。

快速开始

1. 安装服务。 然后在标准输入关闭的情况下启动它。它会打印写入类的状态，并以代码 0 退出。

pip install mcp-server-malcolm
mcp-server-malcolm < /dev/null
# [mcp-server-malcolm] write classes: alerting=off arkime-tag=off hunt-job=off pcap-upload=off arkime-view=off

2. 在 Claude Code 中注册。 将各项值替换为你自己的值。

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

-- 后的所有内容都是启动命令。每个 -e 都会为其设置一个环境变量。在此命令中输入的密码会保留在 shell 历史记录中。安装页面介绍了如何避免这种情况，也涵盖了其他 MCP 客户端和其他安装方式。

3. 检查连接。 请 Agent 调用 malcolm_ping。如果调用失败，请阅读故障排除。最常见的原因是自签名证书。

连接设置

变量	默认值	含义
MALCOLM_URL	https://localhost	Malcolm 的基础 URL
MALCOLM_USERNAME	admin	基本身份验证用户名
MALCOLM_PASSWORD	admin	基本身份验证密码
MALCOLM_SSL_VERIFY	true	true、false 或 CA 证书包的路径

Malcolm 随附自签名证书。对于远程 Malcolm，请将 MALCOLM_SSL_VERIFY 指向 CA 证书包。证书必须包含与主机名匹配的 subjectAltName。Malcolm 自带的安装程序生成的证书不包含此项，因此请安装包含该项的证书。仅在隔离的实验室计算机上使用 false。配置页面列出了所有变量。

默认只读

写入工具分为五类，每类都有一个标志。只有设置标志后，服务才会注册写入工具。未启用的类别不会注册，其中的工具也不会出现在 tools/list 中。

类别	标志	工具
告警	MALCOLM_MCP_ENABLE_ALERTING	malcolm_create_alert
arkime-tag	MALCOLM_MCP_ENABLE_ARKIME_TAGS	arkime_add_tags
hunt-job	MALCOLM_MCP_ENABLE_HUNT_JOBS	arkime_create_hunt、arkime_cancel_hunt
pcap-upload	MALCOLM_MCP_ENABLE_PCAP_UPLOAD	malcolm_upload_pcap
arkime-view	MALCOLM_MCP_ENABLE_ARKIME_VIEWS	arkime_create_view、arkime_create_shortcut

只有当标志的值为 true 时，才表示已启用。每次写入尝试都会记录一行审计日志，输出到 stderr 或 MALCOLM_MCP_AUDIT_FILE 指定的文件中。安全页面介绍了相关模型。

工具

该服务有 51 个只读工具，涵盖 Malcolm 筛选器查询、聚合、字段查找、Arkime 会话和数据包、NetBox、Zeek 文件扫描、已保存对象和告警监视器。工具页面列出了所有工具。

每个会话中的工具架构约占 34,000 个令牌。若要节省令牌，可将不需要的组设为 MALCOLM_MCP_DISABLE_READ_GROUPS 的值。例如，设置为 netbox,dashboards,detections,arkime-inventory 后，将保留 34 个工具。请参阅缩减只读工具范围。

非目标

版本 1 特意不包含以下内容：

• 破坏性写入（删除 Arkime 会话、移除标签、用户管理）。
• 无论是否通过标志控制，均不提供原始 OpenSearch 写入或原始 NetBox CRUD 直通功能。
• streamable-http 传输方式（仅支持 stdio）。

仓库结构

├── src/mcp_server_malcolm/    # The server
│   ├── server.py              #   Registers the tools, applies the write gate
│   ├── client.py              #   HTTP client for Malcolm
│   ├── config.py              #   Write-class flags
│   ├── audit.py               #   Audit output
│   └── tools/                 #   Read tools. Write tools are in write/
├── tests/                     # Tests
├── scripts/
│   └── api_parity_check.py    # Compares each tool with the Malcolm API
├── docs/
│   ├── install.md             #   Install, register, other install routes
│   ├── container.md           #   Run in a container
│   ├── configuration.md       #   Connection settings, every variable
│   ├── troubleshooting.md     #   The first call fails
│   ├── tools.md               #   Read tools, write tools, trimming
│   ├── security.md            #   Security model, audit
│   ├── usage.md               #   Demo, filter syntax, examples
│   ├── python.md              #   Use the client from Python
│   ├── design.md              #   Why an MCP layer, protocol notes
│   ├── verification.md        #   Parity check, tested platforms, API endpoints
│   └── zh-TW/                 #   Copy of these pages for README.zh-TW.md
├── Dockerfile                 # Container image
├── server.json                # MCP Registry manifest
├── SECURITY.md                # Report a vulnerability
├── CONTRIBUTING.md            # How to contribute
└── CHANGELOG.md               # Changes per version

开发

pip install -e . pytest pytest-asyncio ruff
ruff check src tests
ruff format --check src tests
pytest

测试不需要 Malcolm 实例。请参阅 CONTRIBUTING.md。

许可证

MIT