Safecast Map MCP

Safecast MCP服务器连接到simplemap.Safecast.org V0.9

一个MCP（模型上下文协议）服务器，它公开 Safecast 将辐射监测数据传输给克劳德等人工智能助手。该服务器提供17个工具，用于查询实时传感器读数和历史辐射测量值，浏览传感器轨迹、光谱数据、分析和教育参考数据。

特性

• 17工具 用于查询Safecast辐射数据
• 实时和历史数据访问：查询实时传感器读数和历史测量值
• 双重运输：SSE和流式HTTP（与Claude.ai配合使用）
• PostgreSQL+PostGIS 用于快速空间查询（使用REST API回退）
• DuckDB分析 用于使用统计和聚合查询
• 结构化运行时日志记录 用于监控工具使用和性能
• 只读 访问公共Safecast数据

工具概述

实时数据访问

Safecast MCP服务器通过专用工具提供对固定传感器（Pointcast、Solarcast、bGeigieZen等）实时辐射数据的访问。这些工具查询 realtime_measurements PostgreSQL数据库中的表，用于从活动传感器检索最新读数。

实时工具

• list_sensors：按位置或类型发现活动固定传感器
• sensor_current：从特定传感器或地理区域获取最新读数
• sensor_history：从固定传感器中提取日期范围内的时间序列数据
• device_history：访问特定设备的历史bGeigie数据和实时传感器数据

备注：实时数据工具需要数据库连接才能访问 realtime_measurements 桌子。如果没有配置数据库，这些工具将返回到Safecast REST API。

工具参考

query_radiation

查找地理位置附近的辐射测量值。返回指定半径内的测量值，按最近值排序。

示例：查找福岛第一核电站5公里范围内的测量值：

{"name": "query_radiation", "arguments": {"lat": 37.42, "lon": 141.03, "radius_m": 5000}}

每个结果包括： id, value （剂量率，单位为uSv/h）， captured_at, location （纬度/经度）， device_id, detector, track_id, has_spectrum，以及 distance_m.

______________________________________________________________________

搜索区域

在地理边界框内查找辐射测量值。

示例：搜索东京都市区：

{"name": "search_area", "arguments": {"min_lat": 35.5, "max_lat": 35.8, "min_lon": 139.5, "max_lon": 139.9}}

______________________________________________________________________

list_tracks

浏览bGeigie导入轨道（批量辐射测量驱动器/行程）。每条轨迹代表在单个bGeigie会话期间收集的一组测量值。

示例：浏览2024年1月以来的曲目：

{"name": "list_tracks", "arguments": {"year": 2024, "month": 1}}

每个结果包括： track_id, filename, detector, file_size, recording_date, created_at, username （上传者）， map_url （直接链接到轨迹视图，如 https://simplemap.safecast.org/trackid/8fCxVw)，可选 uploader 带有用户名和电子邮件的对象。

______________________________________________________________________

search_tracks_by_location

按国家名称或地理边界框查找bGeigie测量轨迹。此工具搜索在指定地理区域内记录的辐射测量行程（轨迹）。使用国家名称方便搜索，或提供边界框坐标进行精确控制。

示例：查找来自南非的所有曲目：

{"name": "search_tracks_by_location", "arguments": {"country": "South Africa"}}

示例：查找2024年日本的曲目：

{"name": "search_tracks_by_location", "arguments": {"country": "Japan", "year": 2024}}

示例：在自定义边界框中查找轨迹（东京地区）：

{"name": "search_tracks_by_location", "arguments": {"min_lat": 35.5, "max_lat": 35.8, "min_lon": 139.5, "max_lon": 139.9, "limit": 100}}

每个结果包括： track_id, filename, detector, file_size, recording_date, created_at, username （上传者）， centroid （轨道的大致中心）， map_url （直接链接到轨迹视图，如 https://simplemap.safecast.org/trackid/8fCxVw)，可选 uploader 带有用户名和电子邮件的对象。

备注：需要数据库连接。国家名称查找支持80多个国家，包括南非、美国、日本、德国、法国、英国、澳大利亚等。

______________________________________________________________________

get_track

检索特定轨道/行程的所有辐射测量值。使用 list_tracks 首先查找曲目ID。

示例：从特定轨迹获取测量值：

{"name": "get_track", "arguments": {"track_id": "8eh5m1"}}

______________________________________________________________________

设备历史

从特定监测设备获取一段时间内的历史辐射测量值。该工具现在支持bGeigie导入数据和实时传感器数据。

示例：从设备获取90天的历史记录：

{"name": "device_history", "arguments": {"device_id": "12345", "days": 90}}

备注：此工具同时查询 markers 表（适用于bGeigie进口）和 realtime_measurements 表（用于固定传感器）提供指定设备的全面历史记录。

______________________________________________________________________

list_sensors

按位置或类型查找活动的固定传感器（Pointcast、Solarcast、bGeigieZen等），返回设备ID、位置、状态和上次读取时间戳。

示例：查找日本的所有Pointcast传感器：

{"name": "list_sensors", "arguments": {"type": "Pointcast", "min_lat": 30, "max_lat": 46, "min_lon": 129, "max_lon": 146}}

备注：需要数据库连接才能访问 realtime_measurements 桌子。

______________________________________________________________________

传感器电流

从特定传感器或地理区域内的所有传感器获取最新读数。

示例：获取特定传感器的最新读数：

{"name": "sensor_current", "arguments": {"device_id": "sensor-123"}}

示例：获取东京所有传感器的最新读数：

{"name": "sensor_current", "arguments": {"min_lat": 35.5, "max_lat": 35.8, "min_lon": 139.5, "max_lon": 139.9, "limit": 50}}

备注：需要数据库连接才能访问 realtime_measurements 桌子。

______________________________________________________________________

传感器历史

从固定传感器中提取日期范围内的时间序列数据。

示例：从传感器获取30天的历史记录：

{"name": "sensor_history", "arguments": {"device_id": "sensor-123", "start_date": "2024-01-01", "end_date": "2024-01-31"}}

备注：需要数据库连接才能访问 realtime_measurements 桌子。

______________________________________________________________________

list_spectra

浏览和搜索伽马能谱记录。返回元数据（文件名、设备、能量范围、位置） 没有 全信道数据。使用 get_spectrum 带着一个 marker_id 从结果中提取全信道数据。

示例：查找所有SPE光谱文件：

{"name": "list_spectra", "arguments": {"source_format": "spe"}}

示例：浏览所有光谱（无过滤器）：

{"name": "list_spectra", "arguments": {}}

示例：获取特定曲目的所有频谱文件：

{"name": "list_spectra", "arguments": {"track_id": "8eh5m1"}}

示例：获取所有频谱文件，不考虑轨道（无过滤器）：

{"name": "list_spectra", "arguments": {"limit": 100}}

每个结果包括： spectrum_id, marker_id, filename, source_format, device_model, channel_count, energy_range, live_time_sec, calibration, created_at，并嵌套 marker 带有位置和track_id。

备注：需要数据库连接。没有REST API回退。

______________________________________________________________________

get_spectrum

获取特定测量点的完整伽马能谱通道数据。返回包括所有信道计数的完整频谱。

示例:

{"name": "get_spectrum", "arguments": {"marker_id": 4902886}}

退货： channels （计数数组）， channel_count, energy_min_kev, energy_max_kev, live_time_sec, real_time_sec, device_model, calibration, source_format, filename，加上标记位置和剂量率。

______________________________________________________________________

辐射信息

获取有关辐射的教育参考信息。返回静态内容。

话题:

• units --uSv/h、CPM、Bq、Sv的解释
• dose_rates --典型的剂量率范围及其含义
• safety_levels --国际安全标准和阈值
• detectors --辐射探测器的类型及其工作原理
• background_levels --按地区划分的自然本底辐射
• isotopes --常见放射性同位素及其性质

______________________________________________________________________

辐射状态

从Safecast数据库中获取按时间间隔分组的总辐射统计数据。由DuckDB+PostgreSQL提供技术支持。

示例：获取年度统计数据：

{"name": "radiation_stats", "arguments": {"interval": "year"}}

______________________________________________________________________

query_extreme_readings

在数据库中查找具有完整位置详细信息的最高或最低辐射读数。不像 radiation_stats 该工具提供聚合，返回具有坐标、设备ID和时间戳的特定测量值。支持按设备或地理区域过滤异常源。由DuckDB+PostgreSQL提供技术支持。

示例：查找全球20个最高读数：

{"name": "query_extreme_readings", "arguments": {"direction": "highest", "limit": 20}}

示例：查找日本（福岛地区）的10个最高读数：

{"name": "query_extreme_readings", "arguments": {"direction": "highest", "limit": 10, "min_lat": 36.5, "max_lat": 38.5, "min_lon": 140.0, "max_lon": 141.5}}

示例：查找除异常设备bGeigie-2113之外的最高读数：

{"name": "query_extreme_readings", "arguments": {"direction": "highest", "limit": 50, "exclude_devices": ["bGeigie-2113"]}}

示例：查找除爱尔兰科克以外的最高读数（已知异常源）：

{"name": "query_extreme_readings", "arguments": {"direction": "highest", "limit": 50, "exclude_areas": "[{\"min_lat\":51.8,\"max_lat\":52.0,\"min_lon\":-8.6,\"max_lon\":-8.3}]"}}

示例：排除设备和地理区域：

{"name": "query_extreme_readings", "arguments": {"direction": "highest", "limit": 50, "exclude_devices": ["bGeigie-2113", "bGeigie-456"], "exclude_areas": "[{\"min_lat\":51.8,\"max_lat\":52.0,\"min_lon\":-8.6,\"max_lon\":-8.3}]"}}

每个结果包括： id, value （µSv/h）， location （纬度/经度）， captured_at, device_id, track_id，以及 detector.

______________________________________________________________________

top_uploaders

统计哪些用户或设备向Safecast上传了最多的辐射测量数据。支持按用户（默认）或设备分组。返回聚合上传计数、单个标记计数、文件大小和相关设备/用户。

示例：按测量计数获取前10名用户：

{"name": "top_uploaders", "arguments": {"limit": 10, "group_by": "user", "sort_by": "marker_count"}}

示例：按测量计数获取顶级设备：

{"name": "top_uploaders", "arguments": {"limit": 10, "group_by": "device", "sort_by": "marker_count"}}

示例：获取2026年按曲目数排名的顶级设备：

{"name": "top_uploaders", "arguments": {"limit": 20, "group_by": "device", "sort_by": "upload_count", "year": 2026}}

按用户分组时，每个结果包括：

• username：上传者名称
• upload_count：上传的曲目文件数
• marker_count：单个测量点总数
• total_size_mb：总数据（MB）
• devices：使用的设备名称数组
• primary_device：最常用的设备或“多个”

按设备分组时，每个结果包括：

• device_name：设备标识符（例如“bGeigie-5149”）
• upload_count：此设备中的曲目文件数
• marker_count：单个测量点总数
• total_size_mb：总数据（MB）
• users：使用此设备的用户名数组
• primary_user：此设备的主要用户或“多个”

______________________________________________________________________

查询分析

获取所有MCP工具的使用统计数据，包括呼叫计数、平均持续时间和最大持续时间。由DuckDB本地日志提供支持。无需参数。

结构化运行时日志记录

该服务器包括全面的结构化日志记录，用于监控AI工具的使用和性能。日志记录系统通过以下方式实现：

• main.go: instrument() 包装器函数，包装每个工具处理程序以捕获执行指标
• duckdb_client.go: LogQueryAsync() 异步将日志写入DuckDB的函数 mcp_query_log 桌子

测井系统：

• 记录时间戳、工具名称、参数、结果计数和查询持续时间
• 提供不阻止工具执行的异步日志记录
• 将日志存储在DuckDB中，以便通过 query_analytics 工具
• 通过以下方式支持可选的持久存储 DUCKDB_PATH 环境变量

这可以更好地观察工具的使用情况，并有助于识别性能瓶颈。

______________________________________________________________________

db_info

返回数据库连接信息、PostgreSQL版本、复制状态和上传计数的诊断工具。无需参数。

______________________________________________________________________

拼

健康检查。退货 "pong"。不需要参数。

REST API

服务器还在与MCP端点相同的端口上公开标准REST API。所有端点都返回JSON，并通过Swagger UI交互式记录。

快速示例：

curl "http://localhost:3333/api/radiation?lat=37.42&lon=141.03&radius_m=5000&limit=10"

更新API文档

Swagger文档生成自 // @Summary, // @Param，以及 // @Router 注释在 rest_*.go 文件夹。更改任何注释后，使用以下命令重新生成：

# Install swag CLI (one-time)
go install github.com/swaggo/swag/cmd/swag@latest

# Regenerate from go/ directory
cd go && swag init -g cmd/mcp-server/rest.go --dir cmd/mcp-server --output cmd/mcp-server/docs

生成的 docs/ 文件夹已提交到仓库中——部署的二进制文件不需要swag CLI。

快速开始

cd go
go build -o safecast-mcp ./cmd/mcp-server/
./safecast-mcp

默认情况下，服务器在端口3333上侦听。它同时为MCP协议端点和REST API提供服务。

打开 http://localhost:3333/docs/ 用于交互式Swagger UI。

环境变量

端点

• 上海证券交易所: /mcp/sse （GET）和 /mcp/message （职位）
• 可流式传输的HTTP: /mcp-http （职位）

Safecast辐射助手（网络聊天）

Safecast MCP服务器包括一个基于网络的人工智能助手，它提供了一个友好的对话界面来查询辐射数据。助理使用 克劳德·海库4.5 在访问完整的MCP工具集的同时，提供快速、经济高效的响应。

现在试试： https://simplemap.safecast.org/ *（网络聊天界面）*

例题

助理可以帮助处理各种与辐射相关的查询：

实时传感器数据：

• “东京附近目前的辐射水平是多少？”
• “向我展示福岛县的所有活动传感器”
• “大阪的最新读数是什么？”
• “我的坐标35.6762139.6503附近有传感器吗？”

历史测量：

• “有史以来最高的辐射读数是多少？”
• “显示2011年3月福岛的测量结果”
• “查找切尔诺贝利附近的辐射数据”
• “2020年东京的平均辐射水平是多少？”

传感器趋势和时间序列：

• “显示传感器点投射的辐射趋势：过去一周的10042”
• “在过去的一年里，这个地方的辐射发生了怎样的变化？”
• “比较2012年和2024年的辐射水平”

光谱数据：

• “查找福岛附近的伽马能谱测量值”
• “显示轨道8eh5m1的频谱文件”
• “在这个地区检测到了哪些同位素？”

汇总统计数据：

• “辐射与去年相比如何？”
• “全球平均背景辐射是多少？”
• “显示2023年的月度统计数据”

教育与参考：

• “µSv/h和CPM有什么区别？”
• “什么是安全辐射水平？”
• “解释辐射探测器的工作原理”
• “什么是正常背景辐射？”

特性

• 会话界面：用自然语言提问
• 实时和历史数据：访问实时传感器读数和存档测量值
• 智能工具选择：根据您的查询自动使用正确的工具
• 格式化表格：传感器数据显示在干净、可读的标记表中
• 可点击地图链接：设备ID和坐标直接链接到地图
• 下载对话：将聊天记录另存为markdown
• AI免责声明：所有回复都包含一条关于人工智能生成内容的说明

运行自己的网络聊天

网络聊天服务器包含在 go/cmd/web-chat/ 目录：

cd go/cmd/web-chat
export ANTHROPIC_API_KEY=sk-ant-...
export MCP_URL=http://localhost:3333/mcp-http  # optional
export CLAUDE_MODEL=claude-haiku-4-5-20251001  # optional (default: claude-sonnet-4-5)
export PORT=3334                               # optional
go run main.go

然后打开 http://localhost:3334 在您的浏览器中。

环境变量：

• ANTHROPIC_API_KEY （必需）：您的Anthropic API密钥
• MCP_URL （可选）：MCP服务器端点（默认值： http://localhost:3333/mcp-http)
• CLAUDE_MODEL （可选）：要使用的Claude模型（默认值： claude-sonnet-4-5)
• PORT （可选）：Web服务器端口（默认值： 3334)

注： 生产部署在 simplemap.safecast.org 使用Claude Haiku 4.5实现最佳性能和成本效益。

将克劳德连接到MCP

克劳德代码（CLI）-推荐

使用Claude Code CLI添加MCP服务器的最快方法：

# Add the production server
claude mcp add --transport http safecast https://simplemap.safecast.org/mcp-http

# Or add with user scope (available in all projects)
claude mcp add --transport http safecast --scope user https://simplemap.safecast.org/mcp-http

管理命令：

claude mcp list              # List all configured servers
claude mcp get safecast      # View server details
claude mcp remove safecast   # Remove if needed

Claude.ai（Web界面）

要通过web界面连接：

1. 打开 claude.ai 在浏览器中
2. 首选 设置 （左下）> 集成
3. 点击 添加更多 > 添加自定义集成
4. 输入名称（例如“Safecast”）并粘贴可流式传输HTTP端点URL：

   https://simplemap.safecast.org/mcp-http

1. 点击 保存 --Safecast工具现在将在您的对话中可用

本地运行

要将Claude连接到本地运行的MCP服务器：

1. 启动本地MCP服务器：

   cd go
   go run ./cmd/mcp-server/

1. 服务器将于启动 http://localhost:3333 默认情况下

1. 使用ngrok等工具将您的本地服务器暴露到互联网上：

   ngrok http 3333

1. 以ngrok提供的HTTPS URL为例（例如。， https://abc123.ngrok.io)并附加 /mcp-http 以形成端点URL（例如。， https://abc123.ngrok.io/mcp-http)

1. 按照上述“使用部署的服务器”部分的步骤2-5进行操作，使用您的ngrok URL

配置说明

• MCP服务器支持SSE和流式HTTP传输
• 流式HTTP端点(/mcp-http)建议用于Claude集成
• 如果使用自定义域或其他端口，请相应地调整端点URL
• 确保您的服务器可以从互联网访问，以便克劳德连接

建筑

Claude / AI client
    |
    v
MCP Server (Go, mcp-go)
    |
    +---> Tool Execution with Structured Logging
          |
          +---> PostgreSQL + PostGIS (primary, if DATABASE_URL set)
          |     |
          |     +---> markers table (historical bGeigie data)
          |     |
          |     +---> realtime_measurements table (real-time sensor data)
          |     |
          |     +---> spectra table (spectroscopy data)
          |
          +---> DuckDB Analytics Engine
          |     |
          |     +---> Local usage statistics
          |
          +---> Structured Logging System
                |
                +---> Session tracking
                |
                +---> Performance metrics
                |
                +---> Error logging
                |
                +---> Optional external export
    |
    +---> simplemap.safecast.org REST API (fallback)

服务器使用 mcp-go 用于MCP协议支持。所有工具首先尝试直接数据库查询，如果未配置数据库或查询失败，则返回到Safecast REST API。实时数据工具专门查询 realtime_measurements 电流传感器读数表。

项目结构

go/cmd/mcp-server/
  main.go              # Server setup, tool registration, dual transport, instrumentation
  api_client.go        # Safecast REST API client
  db_client.go         # PostgreSQL connection pool (pgx)
  duckdb_client.go     # DuckDB analytics engine, async logging (LogQueryAsync)
  reference_data.go    # Static radiation reference data

  # MCP Tools
  tool_query_radiation.go
  tool_search_area.go
  tool_list_tracks.go
  tool_get_track.go
  tool_device_history.go
  tool_get_spectrum.go
  tool_list_spectra.go
  tool_radiation_info.go
  tool_list_sensors.go
  tool_sensor_current.go
  tool_sensor_history.go
  tool_analytics.go    # query_analytics, radiation_stats tools
  tool_db_info.go

  # REST API
  rest.go              # REST handler, Swagger UI, theme CSS
  rest_radiation.go
  rest_area.go
  rest_tracks.go
  rest_device.go
  rest_sensors.go
  rest_spectra.go
  rest_stats.go
  rest_info.go

  # Generated Documentation
  docs/
    docs.go            # Generated by swag init
    swagger.json
    swagger.yaml

  # Static Assets
  static/
    favicon.ico
    favicon-16x16.png
    favicon-32x32.png

发展

cd go
go run ./cmd/mcp-server/

Linux部署的交叉编译：

cd go
GOOS=linux GOARCH=amd64 go build -o safecast-mcp ./cmd/mcp-server/

部署

推到 main 自动构建和部署到 simplemap.safecast.org （地图服务器）通过GitHub Actions（仅当Go源文件， go.mod/go.sum，或者工作流本身发生了变化）。

重要：域使用CloudFront CDN。SSH部署必须使用服务器IP（65.108.24.131），而不是域名。看 CloudFront部署指南 了解详情。

备注：MCP服务器与数据库在同一台服务器上运行，以获得最佳性能（本地主机连接消除了网络延迟）。看 MIGRATION_TO_MAP_SERVER.md 有关迁移的详细信息。

运作原理

1. GitHub Action交叉编译Go二进制文件
2. 通过rsync将其上传到地图服务器
3. 创建 .env 具有localhost数据库连接的文件
4. 通过systemd重新启动MCP服务器
5. 为配置nginx代理 /mcp-http, /docs/，以及 /api/ 端点
6. 对以下对象进行健康检查 /mcp-http 端点

设置秘密

GitHub Action需要两个存储库机密。首选 设置 > 秘密与变量 > 行动 并添加：

⚠️ 关键： 使用IP地址 65.108.24.131 为了 MAP_SERVER_HOST, 不 simplemap.safecast.org。该域使用不处理SSH流量的CloudFront CDN。

要生成部署密钥，请执行以下操作：

ssh-keygen -t ed25519 -C "github-deploy-mcp@simplemap" -f ~/.ssh/safecast-mcp-deploy -N ""

然后将公钥添加到地图服务器（使用IP地址）：

ssh-copy-id -i ~/.ssh/safecast-mcp-deploy.pub root@65.108.24.131

并粘贴以下内容 ~/.ssh/safecast-mcp-deploy （私钥）作为 SSH_PRIVATE_KEY GitHub上的秘密。

手动部署

⚠️ 重要： 领域 simplemap.safecast.org 使用CloudFront CDN，它只处理HTTP/HTTPS流量。对于SSH/SCP部署，您 必须使用服务器IP地址 （65.108.24.131），而不是域名。

cd go
GOOS=linux GOARCH=amd64 go build -o safecast-mcp ./cmd/mcp-server/
scp safecast-mcp root@65.108.24.131:/root/safecast-mcp-server/
ssh root@65.108.24.131 "systemctl restart safecast-mcp"

为什么是IP地址？ CloudFront在端口80/443（HTTP/HTTPS）上运行，不转发SSH流量（端口22）。当您通过SSH连接到域名时，它会尝试连接到CloudFront的服务器，而不是实际的服务器。

贡献

欢迎捐款。如果更改工具的界面，请先打开问题。叉，分支，PR。

许可证

麻省理工学院

技术实施细节

CORS处理

应用程序通过底层管理的标准HTTP标头处理跨源资源共享 mcp-go 图书馆。

对数标度

用于将辐射值映射到标记不透明度和颜色强度等视觉属性，以便更好地可视化各种值。

时间戳转换

该应用程序将来自API的Unix时间戳转换为可人工调整的格式，以便在地图弹出窗口中显示。

响应式设计

该应用程序使用响应式CSS技术适应各种屏幕尺寸。

API集成详细信息

• 使用的端点:

- /mcp/sse （SSE运输） - /mcp/message （消息传输） - /mcp-http （可流式传输HTTP）

• 数据类型：包含辐射测量、传感器信息和光谱数据的JSON响应
• 请求方法：支持GET（用于SSE）和POST（用于消息传递）

浏览器兼容性要求

• HTML5/CSS3/ES5+兼容浏览器
• SSE通信的WebSocket支持
• 用于处理MCP协议消息的现代JavaScript引擎

部署说明

• 应用程序 必须 通过HTTP（S）服务器提供服务-由于CORS限制和API通信要求，浏览器中的直接文件打开将无法工作。
• 需要后端服务器来处理与Claude等AI客户端的MCP协议通信。