fldigi-mcp

fldigi-mcp

人気のアマチュア無線デジタルモデムアプリケーションである fldigiを、Claude Desktop などの MCP 対応クライアントから操作するための MCP サーバーです。

fldigi には XML-RPC 制御インターフェースが組み込まれています。fldigi-mcp はこのインターフェースに接続し、 API 全体を論理的にグループ化した少数の MCP ツールとして公開します。これにより、アシスタントは平易な言葉で 無線機の状態を読み取り、モデム、無線機、ログ、送信機を操作できます。

ステータス： ベータ版です。信号探索（受信音声から局を見つけ、名前を付けて同調する機能、0.2.0）と、完全な API 対応（fldigi の 174 個すべての XML-RPC メソッドに名前付きオペレーション経由でアクセス可能であることをテストで検証）、コールサインによる送信制御、任意で有効にできる実験的なバンドガイダンス機能を備えています。最新の fldigi リリース 4.2.13 に対応しており、2026-09-09 に実機で検証済みです。

📻 実機で検証済みの fldigi XML-RPC API リファレンス（無料のコミュニティ向け資料）

このサーバーの開発にあたり、fldigi の XML-RPC インターフェース全体を調査し、 実際に稼働するビルドで全メソッドを検証しました。その成果をすべて文書にまとめて無料で公開しています。この MCP サーバーを使うかどうかにかかわらず、ぜひご利用ください。

• docs/fldigi-api.md — 名前空間ごとに整理した、明快で網羅的な、人が読みやすいリファレンスです。通信の詳細、型、実例、送信時の安全性に関するセクション、実地で確認した注意点を掲載しています。
• docs/fldigi-api.pdf — 同じ内容を印刷用 PDF にしたものです。
• docs/fldigi-api-spec.md — 174 個すべてのメソッド（引数、戻り値の型、読み取り／書き込み／送信操作）を簡潔にまとめた機械可読のカタログです。

2026-09-09 に fldigi.list を使用し、fldigi 4.2.13 で実機検証済みです（メソッド一覧は 4.2.11 と同一で、初回検証日は 2026-06-23 です）。公開 Wiki よりも網羅的かつ最新の内容で、Wiki に掲載されていないメソッド（例：TxID）を文書化し、非推奨のメソッドにも注記しています。独立したプロジェクトであり、fldigi / W1HKJ プロジェクトとは関係ありません。 修正は issues / PRs からお寄せください。

特長

• 完全な制御 — fldigi 4.2.13 の XML-RPC メソッド 174 個すべてに、グループ化されたツール内の名前付きオペレーションからアクセスできます（権限はそれぞれ 1 つです。22 個すべてのツールはツールに記載しています）。 tests/test_coverage.py は、同梱カタログのメソッドが配線されていない場合、または引数の型が fldigi のシグネチャと異なる場合に、ビルドを失敗させます。新しいビルドで追加される可能性のあるメソッドには、引き続き fldigi_call で対応できます。
• デフォルトで安全 — コールサインが唯一の送信ゲートです。コールサインを設定しない場合、局は受信専用となり、無線機を送信状態にすることはできません。
• fldigi と同じ名称 — ツールとオペレーションの名称は、fldigi 独自の API 名前空間と画面上のラベル（Op Mode、AFC、SQL、Rev、Lock、RxID/TxID、T/R）に合わせています。
• 不安定な依存関係なし — Python 標準ライブラリの xmlrpc.client を使って fldigi と通信します。サードパーティ製の実行時依存関係は、MCP SDK と PyYAML（任意のバンドプランデータ用）のみです。

XML-RPC を選んだ理由（サードパーティ製ライブラリではなく）

fldigi の XML-RPC インターフェースは、公式の OS に依存しない制御 API です。このプロジェクトは、保守されていないラッパーを介さずに直接通信することで、構成要素を Python 標準ライブラリと fldigi 独自の API に絞っています。

要件

デスクトップ拡張機能（.mcpb）をインストールするために必要なのは、次のものだけです。

• fldigi が起動していること（XML-RPC サーバーはデフォルトで 127.0.0.1:7362 で稼働します）。

Claude Desktop の uv ランタイムが Python と依存関係を提供するため、エンドユーザーが Python や uv を自分でインストールする必要はありません。（このランタイムは現在、実験的とされています。そのため、最近の Claude Desktop のご利用をおすすめします。）

ソースから開発する場合は、これらに加えて Python 3.10+ と uv が必要です（MCP Inspector を使用する場合に限り、Node.js も必要です）。

インストール

最も簡単：ワンクリックのデスクトップ拡張機能

最新の リリースからfldigi-mcp.mcpbをダウンロードし、Claude Desktopで設定 → 拡張機能 → 詳細設定 → 拡張機能をインストール… に進み、ファイルを選択してください。 短い設定フォームでコールサインを入力します（それ以外はすべてデフォルト値が設定されています）。 ターミナルもPythonもuvもインストールする必要はありません。

👉 初めての方は、簡単なステップバイステップのインストールガイドをご覧ください。 インストールと安全性のモデルもご覧ください。

ソースから（開発）

git clone https://github.com/sbrunner-atx/fldigi-mcp.git
cd fldigi-mcp
uv sync

次に、Claude Desktopの設定に追加します （macOSでは~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "fldigi": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/fldigi-mcp", "run", "fldigi-mcp"],
      "env": { "FLDIGI_CALLSIGN": "AE5VG" }
    }
  }
}

Claude Desktopを再起動し、「fldigiのステータスは？」と尋ねてください。受信専用で実行するには、envブロックを省略します。

MCP Inspectorで試す

uv run mcp dev src/fldigi_mcp/server.py

Signal Browserパッチ（patches/）— 提案中、まだマージされていません

**ステータス：**2026年9月11日にfldigiのメンテナーへ提案済みです（w1hkj/fldigi issue 55）。 マージされるまでは、以下のメソッド名とフィールドは提案段階のものであり、変更される可能性があります。

fldigiのSignal Browserは、最大30局のPSK、RTTY、またはCWを同時にデコードする左側のパネルですが、XML-RPC APIには含まれていません。patches/fldigi-4.2.13-browser-xmlrpc.patchは4つのファイル（psk_browser.h/.cxx、viewpsk.cxx、xmlrpc.cxx）を変更し、2つのメソッド、browser.get_channels（{channel, freq, active, text}の配列。textはトリミングされず、改行は保持され、最後にクリアしてから蓄積された内容）とbrowser.clearを追加します。browserツールとsignal_hunt method="browser"はこれらを使用し、fldigiにパッチが適用されていない場合はその旨を伝えます。2つ目のパッチpatches/fldigi-4.2.13-rsid-hits.patch（1つ目のパッチに適用）は、rsid.get_hitsとrsid.clearを追加します。検出器が受け入れたRSIDのバーストを{utc, mode, hz}として取得します。RSIDを通知のみの設定にすると、fldigiはモデムを切り替えることなくバンド上のモードを特定し、rsidツールでその一覧を読み取れます。どちらのパッチも提案段階で、まだマージされていません。4.2.13でテスト済みです（macOS、0～-26 dBの合成PSK31局4局：4局すべてが全文コピーされました）。このパッチはSourceForge上のfldigi git HEADに適用でき、上流への提出に向けて準備されています。取り込まれるまでは、パッチを適用してソースからfldigiをビルドしてください：

tar xf fldigi-4.2.13.tar.gz && cd fldigi-4.2.13
patch -p1 < /path/to/fldigi-mcp/patches/fldigi-4.2.13-browser-xmlrpc.patch
./configure --prefix=$HOME/.local/fldigi && make -j8 && make install

ツール

各ツールは1つの権限であり、operation 引数を取ります。たとえば「モードを変更する」は、実行される内部メソッドにかかわらず、1つの権限です。

ツール	制御対象（fldigi の領域）
status	クイックスナップショット：バージョン、モード、周波数、T/R、コールサイン、バンド
diagnostics	接続のトラブルシューティング用のホスト／ネットワーク情報（fldigi への接続なし）
application	プログラム情報、および fldigi プロセスの起動／停止（fldigi.*）
modem	Op Mode／モデムの選択、搬送波、帯域幅、AFC 範囲、Olivia
frequency	ダイヤル周波数とウォーターフォールのサイドバンド
controls	AFC、SQL、Rev、Lock、RxID、TxID、ステータスフィールド
transmit	T/R、Tune、中止、Tx の無効化／有効化、マクロ、送信 — コールサインが必須
rig	CAT 制御：モード、周波数、帯域幅、ノッチ、QSY、メーター
log	ログブック／コンテストの各フィールド、ADIF の最新／全レコード
text	RX／TX テキストとデータストリーム
spot	スポッティング／PSK Reporter
wefax	WEFAX（気象ファクシミリ）モード
navtex	NAVTEX／SitorB モード
flmsg	flmsg（メッセージフォーム）との相互運用
io	ARQ／KISS I/O ポートの選択
legacy	fldigi が引き続き提供する非推奨メソッド。各メソッドには現在の同等機能の名前が付いています
band_guidance	バンド／ウォータリングホールに関する参考情報（実験的）
signal_hunt	受信音声内の信号を見つけて名前を付け、CQ を送信している局をランク付けします（実験的、追加の [hunt] が必要）
tune_to	モデムと搬送波を signal_hunt の候補に設定し、受信のみ行います
browser	fldigi の Signal Browser：デコーダーバンクが保持するすべての局とそのテキスト（patches/ 内の fldigi パッチが必要）
rsid	パスバンド内で受信した RSID バーストと、そのモードおよび周波数を表示します。モデムは切り替えません（patches/ 内の rsid-hits パッチが必要）
fldigi_call	エスケープハッチ — 将来追加されるものも含め、任意のメソッドを名前で呼び出します

実行中のビルドがサポートするすべてのメソッドを列挙するには、application → list_methods を使用してください。4.2.13 では、すべてのメソッドがグループ内に公開されています。fldigi_call は、このコネクターが対応する前に、より新しい fldigi に追加される可能性のあるメソッドを呼び出すためのものです。

設定

変数	デフォルト	用途
FLDIGI_HOST	127.0.0.1	fldigi の XML-RPC ホスト
FLDIGI_PORT	7362	fldigi の XML-RPC ポート
FLDIGI_CALLSIGN	(空)	オペレーターのコールサイン。唯一の送信ゲート — 送信を有効にするには設定してください。空欄の場合、局は受信専用になります
FLDIGI_BAND_GUIDANCE	off	実験的なバンドガイダンス。on にすると有効になります
FLDIGI_REGION	2	バンドガイダンス用の IARU 地域：1、2、3
FLDIGI_PATH	(自動)	fldigi 実行ファイルへの明示的なパス（application launch 用）
FLDIGI_AUDIO_DEVICE	(システムのデフォルト)	信号探索が音声を取り込む入力デバイス。fldigi が使用するデバイスの名前（または名前の一部）、例：iMic
FLDIGI_HUNT_URL	(空)	fldigi と並行して実行する fldigi-mcp-tap の URL。例：http://127.0.0.1:7365。このサーバーがサウンドカードを開けない場合（サンドボックス内での実行、または別のマシンでの fldigi 実行）に使用します。空欄の場合は、ローカル入力デバイスから音声を取り込みます

パッケージ版のデスクトップ拡張機能では、これらは設定フォームに表示されます。ほとんどのユーザーが入力するのはコールサインだけです。

送信の安全性

コールサインは唯一の送信ゲートです。キーイングを行う操作（transmit の tx／tune／run_macro／send、wefax／navtex の送信操作、および fldigi_call 経由のキーイングメソッド）は、FLDIGI_CALLSIGN が設定されていない場合、実行を拒否します。空欄の場合、局は受信専用になります。rx、abort、disable_tx は局を送信状態から解除するため、常に許可されます。空でない値であれば何でも受け付けます（クラブ局、イベント局、バニティコール、移動局、国際コールがすべて使用できます）。docs/install-and-safety.md を参照してください。

バンドガイダンス（実験的、デフォルトでは無効）

任意で利用できる参考機能です。各モードで慣例となっている「ウォータリングホール」を提案し、周波数がデジタルバンド区分から外れている場合に警告します。あくまでガイダンスとデフォルト値を示すものであり、厳しい制限を設けるものではありません。地域（IARU R1/R2/R3）に対応し、160 m～70 cm をカバーします。FLDIGI_BAND_GUIDANCE=on で有効にできます。band_guidance ツールが追加され、modem／frequency の set 操作に参考情報の guidance フィールドが追加されます。バンドプランのデータを正確に把握するのが難しいため、実験的な機能として提供され、デフォルトでは無効になっています。設計とデータについては、docs/band-guidance.md を参照してください。

リモート／分散構成

fldigi は同じマシンで動作している必要はありません。FLDIGI_HOST／FLDIGI_PORT で接続先を指定してください。LAN 接続を受け入れるには、fldigi を実行するマシンで --xmlrpc-server-address 0.0.0.0 を指定して起動する必要があります。また、接続は信頼できる LAN 内にとどめるか、SSH 経由でトンネルしてください（XML-RPC インターフェースには認証がありません）。

サンドボックス化された MCP クライアント（例：Claude Desktop）： クライアントは**127.0.0.1 にしか接続できず、LAN アドレスには接続できないようサンドボックス化された状態で**コネクターを実行します。そのため、正しい fldigi の LAN IP アドレスを指定しても、telnet で接続できるにもかかわらずタイムアウトします。クライアント側のコンピューターでスタンドアロンの mcp-host-bridge リレーを使用してください（fldigi がポート 7362 であることを認識します）。その後、FLDIGI_HOST=127.0.0.1 を設定します。

pipx install mcp-host-bridge             # or download a binary from its releases
mcp-host-bridge install fldigi --to 192.168.1.50

mcp-host-bridge status fldigi／uninstall fldigi で管理できます。同じツールで N3FJP（姉妹プロジェクトの n3fjp-mcp 用）や、その他のローカルサービスにも接続できます。

スキル

skills/ ディレクトリには、実際のオンエア運用からまとめた操作手順であるエージェントスキルが含まれています。リポジトリと .mcpb パッケージに同梱されています。

• signal-hunting — オペレーターがウォーターフォールを読むように、交信する価値のある局を見つけます。signal_hunt は帯域幅とトーングリッドから各信号のモード（RTTY、CW、PSK、Olivia、MFSK、DominoEX、MT63。特性は sigidwiki.com と照合済み）を特定し、その場にとどまって CQ を出している信号を順位付けします。tune_to でモデムと搬送波を設定し、20 秒分のテキストで確認します。pip install 'fldigi-mcp[hunt]'（numpy、sounddevice）とAudio input device 設定が必要です。サーバーが受信機の隣で動作しない場合（サンドボックス、リモート fldigi）は、fldigi-mcp-tap を受信機側で実行し、サーバーが HTTP 経由でアクセスします（Signal-hunt tap URL）。音声がない場合は、fldigi の search_up を順に実行する方法にフォールバックします。既知のモードを含む録音 5 件で検証済みです（5 件中 5 件）。受信専用です。
• fldigi-operating — TX/RX の切り替えを正しく行う方法（transmit → send による ^r の受信への復帰、緊急停止ボタンとしての abort、TX バッファを絶対にポーリングしないこと）、RX バッファのポーリング手順（差分読み取り、エコーバック禁止のルール、再起動の検出）、CQ ループのリファレンスを説明します。ARRL Field Day 2026 で実地検証済みです。

fldigi-mcp Operating Field Guide（PDF）では、これらのスキルと、姉妹プロジェクト n3fjp-mcp の関連スキル contest-operating を解説しています。スキルの概要、インストール方法、AI に初めて触れるオペレーター向けの平易な説明による「初めてのセッション — ハム向け Claude」章、運用標準、特殊ケースの手引き、ARRL Field Day 2026 の実例を書き起こした例が含まれています。

Claude Code／Cowork で使用するには、スキルのディレクトリを ~/.claude/skills/（またはプロジェクトの .claude/skills/）にコピーしてください。

開発

uv sync
uv run ruff check .      # lint
uv run pytest            # tests (no running fldigi required)

テストスイートでは、バンドプランのロジックと操作マップ／型変換を検証します。実行中の fldigi は必要ありません。

ライセンス

GPL-3.0-or-later © 2026 Stefan Brunner (AE5VG)

fldigi-mcp はフリーソフトウェアです。Free Software Foundation が公開する GNU General Public License のバージョン 3、または（任意で）それ以降のバージョンの条件に従って、再配布および改変できます。0.2.2 までは MIT ライセンスでしたが、GPL-3.0-or-later（fldigi 自体が採用しているライセンス）への変更により、このプロジェクトでは fldigi のマルチチャンネル信号ブラウザーなどのコードを直接再利用できます。XML-RPC 経由で fldigi と通信するだけなら、この変更は必要ありませんでしたが、デコーダーを移植するには必要です。