n3fjp-mcp

n3fjp-mcp

一个用于通过支持 MCP 的客户端（例如 Claude Desktop），将业余无线电 QSO 记录到 N3FJP 记录软件——包括 Amateur Contact Log 和 100 多款 N3FJP 竞赛日志程序——的 MCP 服务。

N3FJP 套件中的每个程序都使用相同的 TCP 控制 API。n3fjp-mcp 直接实现该协议（使用 Python 标准库中的 socket，不依赖第三方封装），并将其作为一组按逻辑分组的 MCP 工具提供，使助手能够通过自然语言记录联络、读取日志、执行重复联络检查，以及管理频段和模式。

它是“操作 → 记录”工作流中的记录部分；其姊妹项目 fldigi-mcp 用于操作电台。

**状态：**实验性（v0.3）。已通过 N3FJP 的 ARRL Field Day Contest Log 实测验证，API 版本为 2.2。整个套件共用此协议，但不同竞赛的字段集有所不同——请使用 fields 工具确认。

⚠️ 独立项目——与 N3FJP 无关联

n3fjp-mcp 是 Stefan Brunner（AE5VG） 开发的独立社区项目，经其所有者许可使用“N3FJP”名称。它与 N3FJP Software / Affirmatech 无关联，也未获得其认可或支持。请将此应用的所有支持问题提交至项目问题跟踪器，而非 N3FJP。采用 MIT 许可。“N3FJP”是其所有者的呼号和商标。

亮点

• 自动记录——核心 log 工具会执行真实的 N3FJP 操作流程：设置呼号 → CALLTAB（重复联络检查 + 查询此前的联络记录）→ 设置交换信息 → ENTER，并显示重复联络的响应和新增记录数。
• 覆盖面广——涵盖读取查询、字段读写、搜索/列表、重复联络和实体检查、频段/模式/频率、直接数据库操作，以及可选启用的推送通知；这些功能分组为 9 个工具（每个工具对应一项权限）、一个只读的 diagnostics 工具，以及一个用于处理大量其他命令和未来命令的 n3fjp_call 备用入口。
• 安全设计，适用于可能访问日志数据库的工具：
  • 读取操作标记为只读，客户端可默认设置为始终允许。
  • 写入操作（记录、频段/模式，以及添加、编辑或删除单条记录）设为需要批准，不额外要求带内确认。
  • 除非启用默认关闭的专用开关 N3FJP_ALLOW_DB_WIPE，否则会直接拒绝整个数据库的清除或覆盖操作。
• 名称与 N3FJP 一致——工具和字段沿用 N3FJP 自身的术语（Action ENTER、CALLTAB、TXTENTRY… 输入框、Class/Section 等）。
• 无脆弱依赖——运行时唯一依赖是 MCP SDK。

要求

要安装桌面扩展（.mcpb）：

• 需要运行中的 N3FJP 程序，并在 Settings → Application Program Interface → "TCP API Enabled" 中勾选该选项（API 默认端口为 1100）。

Claude Desktop 的 uv 运行时会提供 Python 和依赖，因此最终用户无需自行安装 Python 或 uv。

要从源代码进行开发，还需要 Python 3.10+ 和 uv（以及 Node.js，仅用于 MCP Inspector）。

安装

最简单的方法：一键安装桌面扩展

从最新的发布版本下载 n3fjp-mcp.mcpb，然后在 Claude Desktop 中打开 Settings → Extensions → Advanced settings → Install Extension… 并选择该文件。简短的设置表单会询问主机和端口（默认值为 127.0.0.1:1100）。无需终端，无需安装 Python，也无需安装 uv。

👉 如果你是初次使用，请按照分步安装指南操作。

从源代码安装（开发）

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

然后将其添加到 Claude Desktop 的配置文件中 （macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "contest": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/n3fjp-mcp", "run", "n3fjp-mcp"],
      "env": { "N3FJP_HOST": "127.0.0.1", "N3FJP_PORT": "1100" }
    }
  }
}

重启 Claude Desktop，然后询问 “N3FJP 的状态是什么？”。

使用 MCP Inspector 试用

uv run mcp dev src/n3fjp_mcp/server.py

工具

每个工具对应一项权限，并接受一个 operation 参数。

工具	默认值	控制内容
status	读取	快照：程序、版本、API 版本、QSO 数量、波段／模式／频率
diagnostics	读取	解析出的主机和端口、此进程的 Python 和主机名、网络接口；不会连接到 N3FJP
query	读取	程序、qso_count、next_serial、日志／设置／共享路径、qso_rate、band_mode_freq
fields	读取	读取一个输入框，或列出可见／所有字段及其值
search	读取	列出近期记录、搜索、查重（无副作用）、实体状态
log	需批准	log_qso（设置呼号 → CALLTAB → 交换信息 → ENTER）、set、set_many、calltab、enter、clear、focus
bandmode	需批准	change_freq、set_band、set_mode、ignore_rig_polls
notifications	需批准	启用／停用推送事件、清空缓冲事件
database	需批准	add_direct、删除记录、原始 SQL、checklog、openlog、sqlclose
n3fjp_call	需批准	应急通道——发送任意原始命令，包括未来新增的命令

所有写入工具都属于需批准级别，因此你可以在客户端将它们设为始终允许，以实现无人值守自动化。唯一的例外是清空整个数据库（见下文），无论如何都会被硬性阻止。

核心操作是 log → log_qso：

log_qso  call="W1AW"  contest="field_day"  exchange={"class":"2A","section":"CT"}

此操作会设置呼号、触发 CALLTAB（查重）、填入交换信息、发送 ENTER，并报告新增记录及任何重复记录详情。

配置

变量	默认值	用途
N3FJP_HOST	127.0.0.1	N3FJP API 主机
N3FJP_PORT	1100	N3FJP API 端口（套件默认值）
N3FJP_TIMEOUT	6	套接字／响应超时时间，单位为秒
N3FJP_ALLOW_DB_WIPE	off	危险。 允许删除／覆盖整个数据库（原始 SQL DROP／TRUNCATE／不限定范围的 DELETE／UPDATE）。除非你确实有此需要，否则请保持关闭

在打包的桌面扩展中，这些选项会显示为设置表单。

安全模型

记录日志不会操作发射机，因此没有发射门控。这里的保护针对的是你的日志数据库：

• 读取操作（status、query、fields、search）标记为只读——客户端可以默认将它们设为始终允许。
• 写入操作——记录日志（log）、波段／模式（bandmode）、通知，以及添加、编辑或删除单条记录（database），再加上 n3fjp_call 应急通道——都属于需批准级别。没有额外的带内确认，因此你可以在客户端将它们设为 始终允许，让自动化无人值守运行。
• 整个数据库操作——可能删除或覆盖整个日志的原始 SQL（DROP、TRUNCATE、不带 WHERE 的 DELETE／UPDATE）——是唯一的例外：除非启用 N3FJP_ALLOW_DB_WIPE，否则会被拒绝。此开关独立于客户端的批准提示，限制也更严格，并且设置表单中会附有严厉警告。启用前务必备份日志。

只要可能，n3fjp-mcp 都会依赖 N3FJP 自身的验证（它会查重并报告异常情况），并将其响应直接呈现出来，而不是重新实现这些逻辑。

远程／竞赛电台设置（N3FJP 在另一台计算机上运行）

N3FJP 只能在 Windows 上运行。如果 N3FJP 和 Claude Desktop 运行在同一台 Windows 计算机上，将 N3FJP_HOST 保持为 127.0.0.1 即可。在 Mac 上，N3FJP 始终运行在别处：Windows 虚拟机（Parallels、VMware Fusion、UTM）中，或局域网上的 Windows PC 上。虚拟机有自己的网络地址，因此相当于另一台计算机，需要使用下面的桥接工具。

如果 N3FJP 运行在另一台计算机上，会遇到一个问题：沙盒化的 MCP 客户端（尤其是 Claude Desktop）运行连接器时，只能访问 127.0.0.1，无法访问局域网地址。因此，即使 telnet 能连接到 N3FJP 的局域网 IP，在设置中填入该 IP 也会导致超时。可在客户端计算机上使用独立的 mcp-host-bridge 工具解决此问题，然后将主机设置为 127.0.0.1：

pipx install mcp-host-bridge            # or download a binary from its releases
mcp-host-bridge install n3fjp --to 192.168.1.50   # knows n3fjp = port 1100; auto-starts

使用 mcp-host-bridge status n3fjp / uninstall n3fjp 管理它。详情请参阅 docs/REMOTE-HOST.md 和 mcp-host-bridge README。 diagnostics 工具可以帮助确认是否需要使用它。请确保连接仅在可信任的局域网上开放——该 API 未经过身份验证。

文档

📻 经实战检验的 N3FJP API 参考（免费社区资源）

构建此服务意味着要对 N3FJP TCP API 进行逆向工程和实时验证，其中包括如今的 API（v2.2）与公开的 0.9 文档存在差异的几个方面。我们将相关内容整理成一份完整、易读的指南，并免费分享，以回馈社区：

• N3FJP TCP API — 经实战检验的参考指南 （PDF）——传输方式、按领域分组的所有命令、经验证的响应示例、竞赛交换字段，以及一份来之不易的注意事项章节（API 与网络端口、CMD_NOT_FOUND、自 0.9 以来删除的命令、CALLTABEVENT 查询，以及为什么 ENTER 报告 0 时仍可能在联网模式下记录日志）。
• 机器可读规范——以简明、结构化的命令目录形式呈现相同信息，适用于代码生成。

欢迎提出修正和补充——请 提交 issue 或 PR。

项目文档

• 安装指南和测试计划。
• 2026 年 Field Day 经验总结——使用 n3fjp-mcp + fldigi-mcp 运行自主 BPSK31 Field Day 电台（2A 级，呼号已匿名化）的完整事后报告：操作流程、实战中遇到的特殊情况，以及改进建议。

技能

skills/ 目录包含 Agent 技能——从实战通联中提炼出的操作流程，与代码仓库和 .mcpb 软件包一同发布：

• contest-operating——竞赛 QSO 状态机（CQ → 交换信息 → TU → 记录日志）、特殊情况应对手册（QRM、呼号听不清、重复通联、无法抄收时的重复呼叫、仅报呼号的呼叫者），以及经过验证的 N3FJP 日志记录流程和已知问题。 曾在 2026 年 ARRL Field Day 中经实战检验。

操作技能实战指南 （PDF）介绍了此技能，以及来自同一项目 fldigi-mcp 的配套技能 fldigi-operating 和 signal-hunting——技能概览、安装说明、面向 Claude 新用户的通俗易懂的“首次使用”章节、操作规范、特殊情况应对手册，以及根据 2026 年 ARRL Field Day 实战记录整理的示例。

如需与 Claude Code / Cowork 搭配使用，请将技能目录复制到 ~/.claude/skills/（或项目的 .claude/skills/）中。搭配 fldigi-mcp 的 fldigi-operating 技能即可控制电台。

开发

uv sync
uv run ruff check .      # lint
uv run pytest            # tests (no running N3FJP required)
python3 smoke_test.py 192.168.1.50 1100   # Phase 0: prove the link to N3FJP

测试套件涵盖线路协议、操作映射和字段目录、类型强制转换，以及权限和数据库清除安全模型；这些测试都不需要运行 N3FJP。

许可证

MIT © 2026 Stefan Brunner (AE5VG)