meteor-mcp

Meteor scatter planning for amateur radio: can these two stations work each other on this shower, and when.

That is the whole shape of it. Meteor scatter is a point-to-point mode, so a radiant elevation on its own tells an operator nothing they can act on — the question is always about a path between two stations.

Part of the qso-graph project.

What decides a meteor-scatter contact

Three things, and radiant elevation is only one of them.

1. Path length. Trails burn at about 85–120 km, so a single-hop reflection off something that low works from roughly 400 km to about 2300 km. Shorter and the reflection point would have to be nearly overhead, where there is very little qualifying sky; longer and it sits below both horizons. 800–2000 km is where the geometry is best, and it is what hams actually run.

2. Radiant elevation at the path midpoint — not at either station. The reflection happens near the middle, so that is the sky that matters. Below the horizon there are no trails to reflect from. Very high is also poor, because trails then run down the path rather than across it.

3. The angle between the radiant and the path. This is the one usually left out, and it is the one that decides whether a reflection is geometrically possible at all. A trail reflects specularly only where it is tangent to the ellipsoid with both stations at its foci. Trails running along the path can never be tangent to it; trails running across it can. So a radiant broadside to the path is good and a radiant up- or down-path is poor — at the very same elevation.

All three are reported, and the verdict says which one decided it.

Why there is no score out of a hundred

Because the physics above is a tangency condition, and what a station actually hears also depends on its power, its antenna and the sporadic background. A figure like "73" would imply a precision none of that supports. So the answer is no / marginal / good / best, each with the reason beside it.

Where the numbers come from

Shower radiants, numbers and names are the IAU Meteor Data Center's — the body that names and numbers meteor showers. The package carries the facts read from the MDC's Established showers file with its URL and SHA-256 recorded, so the exact edition served is identifiable. The MDC is maintained on an unpaid voluntary basis and asks to be cited; its requested references are returned by meteor_source_info, printed in NOTICE, and travel inside every answer that uses a radiant.

The MDC lists several published solutions per shower, each from a different study. All of them are kept and none is blended — the average of two published radiants is a third that nobody published and no paper stands behind. Tools return the first-listed solution, labelled, and meteor_shower_info gives them all.

Peaks are stored as solar longitude, not as dates, because that is how the catalogue publishes them and it is the right way round: solar longitude names the same point in the stream every year, while a date drifts. This server converts it to the date it falls on in the year you ask about.

Two tools read the network, because only those two report what is happening right now:

Everything else is computed locally and needs no network at all.

Your own end comes from your station profile

meteor_window needs both ends of the path, but you should not have to retype your own. Your end is optional, and a host that knows the operator's station supplies it — in QG Desktop that is the Station component.

The fields are ADIF's, not invented here:

A grid is what hams actually use, so a locator is the normal input here, not a degraded one. It may carry 4, 6 or 8 characters. Operators often state 6 or 8 for their own station, while a structured on-air exchange may carry only 4. Which modes constrain it is not asserted here: ADIF enumerates every mode and submode but says nothing about payload length, so there is no authority to infer precision from mode — 4 is the safe floor for all of them.

A grid square is a rectangle, though, and its centre is all a locator gives. Nothing here assumes a precision: the slack is computed from the characters each locator actually carried. At 4 characters that is about ±100 km per end, so a path length carries about ±200 km of slack; at 6 it falls to a few km. That is immaterial on a 1100 km path and decisive against a threshold — a path reported as 2250 km could be 2050 to 2450, which straddles the 2300 km single-hop limit. When a limit falls inside that slack the answer says the call cannot be decided at on-air precision, and what would settle it. The slack is reported either way.

So MY_LAT/MY_LON are used when a station has them, and the answer always says which it used and how precisely each end was located.

A 2-character MY_GRIDSQUARE is a legitimate ADIF value but is refused for a path: a Maidenhead field is 10 by 20 degrees, around 1100 km across, which is wider than the entire usable meteor-scatter range. The refusal explains the precision rather than calling the locator invalid, because it isn't.

Home, portable, and remote all work the same way

ADIF's location fields describe the transmitting station, not where the operator is sitting — MY_LAT is "the logging station's latitude". That is what makes a remote operation come out right without a special case: the reflection geometry depends on where the antenna is. ADIF separates the three callsigns for exactly this reason — STATION_CALLSIGN (used over the air), OPERATOR (the person), and OWNER_CALLSIGN ("the callsign of the OPERATOR's host").

So operating a remote station in FN42 from a chair in DN13 gives the FN42 path, and the operator's own location never enters the calculation.

Install

uvx meteor-mcp            # run it; nothing to install

No credentials, no accounts, no configuration.

Tools

A count is not a flux

meteor_activity returns the number of confirmed trajectories the Global Meteor Network has recorded today, broken down by IAU shower code. That is not a flux density — meteoroids per square kilometre per hour, corrected for camera coverage and limiting magnitude — which is a different quantity GMN computes separately. The tool is named and documented for what it actually returns. GMN writes the file during the day, so an early read covers a partial day; the generation time comes back with the answer.

Quick Start

Configure your MCP client

meteor-mcp works with any MCP-compatible client. Add the server config and restart.

Claude Desktop

Add to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "meteor": {
      "command": "uvx",
      "args": ["meteor-mcp"]
    }
  }
}

Claude Code

Add to .claude/settings.json:

{
  "mcpServers": {
    "meteor": {
      "command": "uvx",
      "args": ["meteor-mcp"]
    }
  }
}

ChatGPT Desktop

Configure via Settings > Apps & Connectors, or in your agent definition:

{
  "mcpServers": {
    "meteor": {
      "command": "uvx",
      "args": ["meteor-mcp"]
    }
  }
}

Questions it answers

"Can I work EM12 from DN13 on the Perseids tonight, and when?"

"Which meteor showers are near their peak this week?"

"Is the radiant going to be broadside to my path or up it?"

"Is 2100 km too far for single-hop meteor scatter?"

"How many meteors has the Global Meteor Network actually seen today?"

"Show me every published radiant for the Geminids, not an average."

"Were there any fireballs this week?"

Pointing

Point both antennas near the path bearing, not at the radiant. The reflection happens near the path midpoint; the radiant's position decides whether a trail there can be tangent to your path, not where to aim.

Licence

GPL-3.0-or-later. See LICENSE.