mcp-server-pskreporter

PSK Reporter MCP サーバー

Claude Desktop 経由で PSKReporter のリアルタイムなアマチュア無線伝搬データを提供する Model Context Protocol（MCP）サーバーです。

特徴

• リアルタイムの伝搬データ：世界中のアマチュア無線局からライブスポットを収集します
• 高度なフィルタリング：バンド、モード、コールサイン、場所、国で絞り込めます
• DXCC エンティティのサポート：名称のバリエーションを適切に処理する、国・地域の包括的なマッピングを備えています
• MCP リソース：利用可能な国と、その一般的な名称のバリエーションを確認できます
• スレッド化アーキテクチャ：応答性の高いパフォーマンスを実現する、ノンブロッキングな MQTT 収集方式を採用しています

インストール

前提条件

• Python 3.13 以降
• uv パッケージマネージャー
• Claude Desktop アプリケーション

セットアップ

1. このリポジトリをクローンまたはダウンロードします

   git clone <your-repo-url>
   cd mcp-server-pskreporter
   

2. uv で依存関係をインストールします

   uv sync
   

3. インストール方法を選択します：

   オプション A：開発モード（コマンドを直接実行する場合）

   uv pip install -e .
   

   これにより、ローカルの仮想環境にパッケージが開発モードでインストールされ、このプロジェクトの環境内で pskreporter-mcp-server コマンドを利用できるようになります。プロジェクトディレクトリからコマンドを直接実行する場合に選択してください。

   オプション B：プロジェクトから実行（Claude Desktop 用 — インストール不要）

   uv run --project . pskreporter-mcp-server
   

   これにより、インストールせずにプロジェクトディレクトリからサーバーを直接実行します。Claude Desktop では、デフォルトでこの方法を使用します。

4. サーバーが動作することを確認します

   オプション A（開発モード）を使用した場合：

   # Make sure you're in the project directory
   pskreporter-mcp-server
   

   オプション B（プロジェクトから実行）を使用した場合：

   uv run --project . pskreporter-mcp-server
   

   サーバーが起動し、MCP 接続を受け付ける準備が整います。

Claude Desktop への追加

方法 1：設定ファイルを使用する（推奨）

1. 設定ファイルを Claude Desktop の設定ディレクトリにコピーします：

   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. claude_desktop_config.json のパスをシステムに合わせて変更します：

   {
     "mcpServers": {
       "pskreporter": {
         "command": "uv",
         "args": ["run", "--project", "C:\\Users\\rokhm\\git\\mcp-server-pskreporter", "pskreporter-mcp-server"],
         "env": {}
       }
     }
   }
   

3. Claude Desktop を再起動します

注：このリポジトリの claude_desktop_config.json ファイルは、現在のパスに合わせて事前設定されています。プロジェクトを移動した場合は、--project 引数のパスもそれに合わせて変更してください。

方法 2：Claude Desktop の UI を使用する

1. Claude Desktop を開きます
2. Settings → MCP Servers に移動します
3. Add Server をクリックします
4. サーバーを設定します：
   • Name：pskreporter
   • Command：uv
   • Arguments：run --project C:\Users\rokhm\git\mcp-server-pskreporter pskreporter-mcp-server
   • Working Directory：C:\Users\rokhm\git\mcp-server-pskreporter（プロジェクトフォルダー）
5. Save をクリックします

方法 3：別のコマンドを使用する

次の方法でもサーバーを実行できます：

Python を直接実行：

python -m pskreporter_mcp_server

uv run を使用：

uv run pskreporter-mcp-server

開発モード：

uv run mcp dev pskreporter_mcp_server.py

使用方法

Claude Desktop に接続すると、次のツールとリソースを使用できます：

get_spots ツール

フィルタリングオプションを使って、アマチュア無線のリアルタイム伝搬スポットを収集します。

パラメーター：

• band：アマチュア無線のバンド（例：「20m」、「40m」、「80m」、「160m」、「10m」、「15m」、「17m」、「30m」、「12m」、「6m」、「2m」）
• mode：運用モード（例：「FT8」、「FT4」、「CW」、「SSB」、「PSK31」、「RTTY」）
• sendercall：特定の局のコールサイン（例：「W9KM」、「JA1ABC」）
• receivercall：受信局のコールサイン
• senderlocator：送信局のメイデンヘッド・グリッドロケーター（例：「EN51」、「JO20」）
• receiverlocator：受信局のメイデンヘッド・グリッドロケーター
• sendercountry：送信局の国名（例：「Japan」、「USA」、「Germany」）
• receivercountry：受信局の国名
• duration：収集時間（秒）（5～30、デフォルト：10）

国名の機能：

• 大文字と小文字を区別しません：「japan」、「JAPAN」、「Japan」はすべて同じように機能します
• 部分一致：「swains」は「Swains I.」に、「korea」は「Republic of Korea」に一致します
• 一般的な別表記：「USA」、「UK」、「Germany」は正式名称に自動的に対応付けられます
• 340以上のエンティティ：世界中を網羅する、DXCCエンティティの完全なサポート

例：

• 「日本からの20mバンドのFT8運用を表示して」
• 「40mバンドのUSAの局を検索して」
• 「W9KMはどのバンドで運用していますか？」
• 「80mバンドのドイツの局を表示して」

dxcc_entities リソース

利用可能な国とその別表記を調べて、フィルタリングをより便利にします。

リソースの機能：

• 完全なエンティティ一覧：正式名称を含む、すべての340のDXCCエンティティ
• 名称の別表記：各国で一般的な別表記（例：「United States of America」の「USA」）
• 使用例：get_spots ツールですぐに使える例
• 検索のヒント：国名を効果的に指定する方法

使用方法：

• 利用可能なすべての国と地域を確認する
• 各国の一般的な別表記を確認する
• get_spots のパラメーターで使用する正確な名称を取得する
• まだ知らない新しいDXCCエンティティを見つける

リソースデータの例：

{
  "code": "291",
  "name": "United States of America",
  "name_variations": ["United States", "USA", "US", "America"]
}

国名の検索

dxcc_entities リソースでは、国に関する包括的な情報を確認できます。

• 正式名称：最良の結果を得るには、正確なDXCCエンティティ名を使用してください
• 一般的な別表記：よく使われる略称や別名
• 大文字と小文字の違いに対応：大文字と小文字の違いにかかわらず、すべての名称を使用できます
• 部分一致：不完全な名称でも国を検索できます

よく使われる例：

• United States：「USA」、「US」、「America」、「United States of America」
• United Kingdom：「UK」、「Great Britain」、「Britain」、「England」
• Germany：「Germany」、「Deutschland」、「DE」
• Japan：「Japan」（一般的な別表記はありません）
• Swains Island：「Swains」、「Swains I.」、「Swains Island」

データソース

このサーバーは、mqtt.pskreporter.info のPSKReporter MQTTフィードに接続し、世界中のアマチュア無線局からリアルタイムの伝搬データを取得します。

トラブルシューティング

よくある問題

1. サーバーが起動しない

   • Python 3.13+ がインストールされていることを確認してください
   • uv がインストールされていることを確認してください：curl -LsSf https://astral.sh/uv/install.sh | sh
   • 依存関係がインストールされていることを確認してください：uv sync

2. スポットが収集されない

   • duration パラメーターを増やしてください（最大30秒）
   • より広いフィルターを使用してください（パラメーターを減らします）
   • インターネット接続を確認してください

3. 国名が見つからない

   • dxcc_entities リソースを使用して、正確な国名を確認してください
   • 一般的な別名を試してください（例：「United States of America」ではなく「USA」）
   • 入力ミスがないか確認し、部分一致を試してください

4. Claude Desktop が接続できない

   • claude_desktop_config.json 内のパスが正しいことを確認してください
   • 手動で実行したときにサーバーが正常に起動することを確認してください：uv run pskreporter-mcp-server
   • Claude Desktop のログでエラーメッセージを確認してください

5. 「File not found」エラー

   • 作業ディレクトリが pskreporter_mcp_server.py を含むフォルダーを指していることを確認してください
   • すべてのプロジェクトファイルが同じディレクトリにあることを確認してください

6. 「program not found」または「Failed to spawn」エラー

   • コマンドを直接実行したときに「Failed to spawn 'pskreporter-mcp-server' caused by: program not found」が表示された場合は、開発モードでパッケージをインストールする必要があります：

     uv pip install -e .
     

   • インストール後、プロジェクトの仮想環境内で pskreporter-mcp-server コマンドを使用できるようになります
   • 注：Claude Desktop は uv run --project を使用するため、インストールは不要です。付属の claude_desktop_config.json は追加設定なしで動作します

デバッグ情報

サーバーは詳細情報を記録したデバッグログファイル mcp_server_debug.log を作成します。記録される情報は次のとおりです：

• MQTT 接続ステータス
• スポット収集の進行状況
• 国名の解決
• エラーメッセージとスタックトレース

開発

このプロジェクトでは、依存関係の管理に uv を使用します。主なコマンド：

• uv sync - 依存関係をインストール
• uv run pskreporter-mcp-server - サーバーを実行
• uv run --project C:\Users\rokhm\git\mcp-server-pskreporter pskreporter-mcp-server - 任意のディレクトリから実行
• python -m pskreporter_mcp_server - Python モジュールとして実行

設定

Claude Desktop の設定

claude_desktop_config.json ファイルは、uv run --project を使用するように事前設定されています：

{
  "mcpServers": {
    "pskreporter": {
      "command": "uv",
      "args": ["run", "--project", "C:\\Users\\rokhm\\git\\mcp-server-pskreporter", "pskreporter-mcp-server"],
      "env": {}
    }
  }
}

主なポイント：

• プロジェクトを直接実行するために uv run --project コマンドを使用します
• --project 引数はローカルのプロジェクトディレクトリを指します
• 事前インストールは不要です（uv が依存関係を自動的に処理します）
• 実行ファイル名は pskreporter-mcp-server（ハイフン区切り）です

DXCC エンティティの設定

サーバーは DXCC エンティティに YAML ベースの設定（dxcc_entities.yaml）を使用します。この設定には次の利点があります：

• 簡単なメンテナンス：国名と別名を、人が読みやすい YAML ファイルに保存します
• 柔軟な更新：コードに触れずに国名の別名を追加または変更できます
• 構造化データ：正式名称と一般的な別名を明確に分けて管理できます

ファイル構造：

dxcc_entities:
  "291":
    canonical_name: "United States of America"
    name_variations: ["USA", "US", "United States", "America"]
  "339":
    canonical_name: "Japan"
    name_variations: []

国名の別名を追加する： 国名の別名を追加するには、dxcc_entities.yaml ファイルを編集します：

1. DXCC コードで国を探します
2. name_variations 配列に別名を追加します
3. 変更を反映するためにサーバーを再起動します

例：

"339":
  canonical_name: "Japan"
  name_variations: ["Nippon", "Nihon"]

サーバーは起動時にこれらの変更を自動的に読み込むため、国名のサポートを簡単に維持、拡張できます。

---

73! Andriy W9KM