mcp-server-malcolm

Malcolm MCP サーバーを使うと、AI エージェントが Malcolm インスタンスのトラフィックについて質問できます。このサーバーは、Malcolm が使用するフィールド名とフィルター構文を使うため、エージェントがそれらを推測する必要はありません。Claude Code、Claude Desktop、Cursor など、あらゆる MCP クライアントで使用できます。

質問の例と、それに回答するツールは次のとおりです。

• 「過去 24 時間に 192.0.2.15 が関係した Suricata アラートをすべて表示し、その IP を所有する NetBox デバイスを教えてください。」この質問では malcolm_alerts と malcolm_netbox_lookup が呼び出されます。
• 「過去 1 時間のプロトコル別の上位トーカーを教えてください。」この質問では malcolm_aggregate が呼び出されます。
• 「昨日のトラフィックから Zeek が抽出した実行ファイルを、ハッシュとともに一覧表示してください。」この質問では malcolm_file_scans が呼び出されます。
• 「この PCAP をアップロードして、保存されたパケットからこの文字列を検索してください。」この質問では malcolm_upload_pcap と arkime_create_hunt が呼び出されます。どちらも書き込みツールで、デフォルトでは無効です。

記録されたセッションでは、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 は、そのコマンドに設定する環境変数を 1 つ指定します。このコマンドに入力したパスワードは、シェルの履歴に残ります。インストールページでは、それを避ける方法を説明しています。また、ほかの MCP クライアントや別のインストール方法も紹介しています。

3. 接続を確認します。 エージェントに malcolm_ping を呼び出すよう依頼してください。呼び出しに失敗した場合は、トラブルシューティングを参照してください。最もよくある原因は、自己署名証明書です。

接続設定

変数	デフォルト	説明
MALCOLM_URL	https://localhost	Malcolm のベース URL
MALCOLM_USERNAME	admin	Basic 認証のユーザー名
MALCOLM_PASSWORD	admin	Basic 認証のパスワード
MALCOLM_SSL_VERIFY	true	true、false、または CA バンドルへのパス

Malcolm には自己署名証明書が付属しています。リモートの Malcolm に接続する場合は、MALCOLM_SSL_VERIFY に CA バンドルを指定してください。証明書には、ホスト名と一致する subjectAltName が含まれている必要があります。Malcolm のセットアップで生成される証明書には含まれていないため、含まれている証明書をインストールしてください。false を使用するのは、隔離されたラボ用マシンに限ってください。設定ページにすべての変数が記載されています。

デフォルトでは読み取り専用

書き込みツールは5つのクラスに分かれており、各クラスに1つのフラグがあります。フラグを設定するまでは、サーバーには読み取りツールのみが登録されます。オフになっているクラスは登録されず、そのツールは 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 の場合のみです。書き込みを試みるたびに、監査ログが1行、標準エラーまたは 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