Resolves beach names to geographic coordinates using OpenStreetMap data (via the Photons geocoder).
Get comprehensive beach and surf conditions for any beach in the world ā just say the name. No API keys needed for most data.
"How's the surf at Waikiki?" ā instant full report
ā If you find this useful, please star the repo ā it helps others discover it.
š Waves ā height, period, direction
š«ļø Swell ā swell height, period, direction
šØ Wind ā speed and direction
š”ļø Temperature ā air and water
āļø UV Index ā current UV + daily max, day/night aware (free, no API key)
ā ļø Rip Current Risk ā Low / Moderate / High
š”ļø Safety Score ā 1-10 with recommendations
Related MCP server: Surf Forecast MCP
Source | Data |
OpenStreetMap / Photons | Beach name ā coordinates |
Open-Meteo Marine | Wave height, swell, ocean currents |
Open-Meteo Weather | Air temp, wind, precipitation, UV index |
NOAA NWS | Rip current risk, surf zone forecast |
UV index data comes from Open-Meteo at no cost ā no API key needed.
git clone <repo-url>
cd beach-safety-mcpOr just copy the src/server.py file to wherever you want it.
mcporter config add beach-safety \
--command python3 \
--args "path/to/beach-safety-mcp/src/server.py" \
--cwd "path/to/beach-safety-mcp/config"Or manually add to ~/.openclaw/workspace/config/mcporter.json:
{
"beach-safety": {
"command": "python3",
"args": ["/full/path/to/beach-safety-mcp/src/server.py"]
}
}mcporter call beach-safety.get_beach_json beach_name="Waikiki"get_beach_report(beach_name="Waikiki")
get_beach_report(beach_name="Bondi Beach, Sydney")
get_beach_report(beach_name="Cocoa Beach, FL")Just say the beach name ā coordinates are auto-resolved.
python3 beach_lookup.py "Waikiki"
python3 beach_lookup.py "Praia da Rocha, Portugal"
python3 beach_lookup.py "Bondi Beach, Sydney"mcporter call beach-safety.get_surf_forecast lat=21.27 lon=-157.82š Bondi Beach, Sydney Beach Conditions
Lat/Lon: -33.8907, 151.2724
Updated: 2026-03-23T10:30:00Z UTC
š”ļø SAFETY (Score: 8/10)
Rip Current Risk: Moderate
Safety: Moderate rip current risk
š WAVES
Wave Height: 2.8 ft (0.84m)
Wave Period: 6.7 sec
Swell: 2.4 ft @ 4.8 sec from E
šØ WIND
Speed: 4.0 mph from NE
š”ļø TEMPERATURE
Air: 68Ā°F | Water: 75Ā°F
āļø UV INDEX: current=6 (daily max=9) (Very High) ā sunscreen recommended
*(at night shows current=0 with daily max, UV risk based on max)*
š RECOMMENDATIONS:
ā ļø Swim near a lifeguard. Be aware of rip currents.Score | Meaning | Action |
9-10 | Generally safe | Enjoy with normal precautions |
7-8 | Minor concerns | Caution advised |
4-6 | Caution | Swim near lifeguard |
1-3 | Dangerous | Stay out of the water |
Works for any beach worldwide ā just name it
NOAA surf zone data is most detailed for US coasts
Open-Meteo marine data covers global oceans
Some less-famous beaches may not resolve ā try adding country/state (e.g., "Kuta Beach, Bali, Indonesia")
Beach name ā coordinates powered by OpenStreetMap + Photons (free)
beach-safety-mcp/
āāā src/
ā āāā server.py # MCP server (Python, stdio)
āāā beach_lookup.py # CLI tool
āāā LICENSE # MIT License
āāā README.mdGet beach conditions as structured JSON for programmatic use. Same as get_beach_report but in JSON format. Auto-geocodes any beach name.
| Name | Required | Description | Default |
|---|---|---|---|
| latitude | No | Latitude (optional) | |
| longitude | No | Longitude (optional) | |
| beach_name | Yes | Name of the beach (e.g., 'Waikiki', 'Bondi Beach') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses that any beach name is auto-geocoded, but says nothing about data freshness, rate limits, error behavior when geocoding fails, or what the JSON payload contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with what the tool returns and immediately followed by the sibling distinction. No filler text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without annotations or an output schema, the description should say more about the returned JSON shape and the read-only/safe nature of the call. It is adequate for invocation but thin for a tool whose value is the structured payload.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline would be 3, but the 'auto-geocodes any beach name' note adds functional meaning by explaining why beach_name alone suffices and latitude/longitude remain optional. It does not add coordinate format or range details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get beach conditions as structured JSON') and explicitly distinguishes itself from the sibling get_beach_report by output format. An agent can route between the two without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives the selecting condition ('for programmatic use', 'JSON format') and names the alternative tool it mirrors, which is clear routing guidance. It stops short of stating when not to use it (e.g., human-readable output should go to get_beach_report).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comprehensive beach safety conditions including rip current risk, waves, swell, wind, temperature, UV, and safety score for any beach location. Automatically geocodes any beach name worldwide ā just say 'Waikiki' or 'Bondi Beach'.
| Name | Required | Description | Default |
|---|---|---|---|
| latitude | No | Latitude (optional ā resolved from name if omitted) | |
| longitude | No | Longitude (optional ā resolved from name if omitted) | |
| beach_name | Yes | Name of the beach (e.g., 'Waikiki', 'Bondi Beach, Sydney', 'Cocoa Beach, FL') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses the meaningful auto-geocoding behavior ('Automatically geocodes any beach name worldwide'), which is real operational context, but says nothing about rate limits, authentication, data freshness, or whether the geocoded coordinates are echoed back. For a read-only conditions tool the risk is low, but several behavioral questions remain unanswered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The capability and the returned data are front-loaded, and the geocoding convenience note follows as a secondary but genuinely useful clarification for input handling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description compensates well by enumerating the returned fields (rip current risk, waves, swell, wind, temperature, UV, safety score). The main residual gap is the absence of any sibling-routing guidance given the overlapping get_surf_forecast and get_uv_forecast tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents beach_name and the optional latitude/longitude fallback. The description adds only marginal value by clarifying that free-text names worldwide are acceptable ('just say Waikiki'), which reinforces but does not extend the schema's own examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Get comprehensive beach safety conditions') and enumerates the exact data returned (rip current risk, waves, swell, wind, temperature, UV, safety score), so the agent knows precisely what the tool produces. It does not explicitly distinguish itself from siblings like get_surf_forecast or get_uv_forecast, which overlap on waves and UV respectively, leaving the agent to infer that this is the broad all-in-one option.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied rather than stated: 'for any beach location' and the auto-geocoding note tell the agent the tool accepts free-text beach names, and the examples ('Waikiki', 'Bondi Beach') show the expected input style. However, there is no explicit guidance on when to prefer this tool over get_surf_forecast or get_uv_forecast, and no exclusions or prerequisites are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a focused surf forecast for any beach: wave height, wave period and direction, swell height/period/direction, rip current risk, and safety score. Accepts a beach name (auto-geocoded worldwide ā just say 'Waikiki' or 'Bondi Beach') or raw coordinates. Use this when only surf conditions are needed; use get_beach_report for the full safety report including wind, temperature, and UV.
| Name | Required | Description | Default |
|---|---|---|---|
| latitude | No | Latitude in decimal degrees (optional if beach_name is given) | |
| longitude | No | Longitude in decimal degrees (optional if beach_name is given) | |
| beach_name | No | Name of the beach (e.g., 'Waikiki', 'Bondi Beach, Sydney'). Auto-geocoded ā provide this or latitude/longitude. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden; it discloses genuinely useful behavioral context by describing the return payload composition and the auto-geocoding input behavior ('auto-geocoded worldwide ā just say Waikiki'). It omits failure modes for unresolvable beach names, rate limits, and auth requirements, which leaves some burden uncovered for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each earning its place: the first is a front-loaded purpose statement with the output inventory, the second covers input handling and sibling routing. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, but the description enumerates the returned fields explicitly and explains the mutually exclusive input modes, so an agent has everything needed to call it correctly. The absence of annotations is partially compensated by the returned-data and geocoding details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters including the anyOf beach_name-or-coordinates constraint. The description restates auto-geocoding and gives examples but adds no new syntax, format, or precedence rules beyond what the schema provides; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get a focused surf forecast for any beach') and enumerates the exact outputs returned (wave height/period/direction, swell metrics, rip current risk, safety score). It explicitly distinguishes itself from the sibling get_beach_report, so an agent can route between them without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use it ('when only surf conditions are needed') and names the alternative with the condition that selects it ('use get_beach_report for the full safety report including wind, temperature, and UV'). This is a direct when/when-not/alternative pairing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the UV index forecast for any beach: current and max UV index, risk level, and sun-protection recommendations. Accepts a beach name (auto-geocoded worldwide ā just say 'Waikiki' or 'Bondi Beach') or raw coordinates. Use this when only sun-exposure info is needed; use get_beach_report for the full safety report.
| Name | Required | Description | Default |
|---|---|---|---|
| latitude | No | Latitude in decimal degrees (optional if beach_name is given) | |
| longitude | No | Longitude in decimal degrees (optional if beach_name is given) | |
| beach_name | No | Name of the beach (e.g., 'Waikiki', 'Bondi Beach, Sydney'). Auto-geocoded ā provide this or latitude/longitude. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It does add useful behavior (beach names are auto-geocoded worldwide, coordinates are an alternative input mode) and lists what comes back, but it never states that this is a read-only, non-mutating call, nor what happens on geocoding failure or unknown beaches.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, followed by input modes and the sibling routing rule. Every clause earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description enumerates the returned fields, covers both input modes, and routes to the alternative tool. The only gap is the absence of error/failure behavior and read-only reassurance for a tool with no annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters, including the optional-if-beach_name-given relationship and the anyOf requirement. The description's examples ('Waikiki', 'Bondi Beach') and geocoding note largely restate the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Get the UV index forecast') and enumerates the exact payload (current and max UV index, risk level, sun-protection recommendations). It also distinguishes itself from the sibling get_beach_report, so an agent can route without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit selection rule: 'Use this when only sun-exposure info is needed; use get_beach_report for the full safety report.' The condition and the named alternative are both present, leaving nothing to inference for the primary routing decision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.4get_surf_forecast2 fields changedInput schema / anyOfAdded value: +[
+ {
+ "required": [
+ "beach_name"
+ ]
+ },
+ {
+ "required": [
+ "latitude",
+ "longitude"
+ ]
+ }
+]Input schema / requiredRemoved value: -[]get_uv_forecast2 fields changedInput schema / anyOfAdded value: +[
+ {
+ "required": [
+ "beach_name"
+ ]
+ },
+ {
+ "required": [
+ "latitude",
+ "longitude"
+ ]
+ }
+]Input schema / requiredRemoved value: -[]v0.1.1get_surf_forecast6 fields changedInput schema / properties / beach_nameAdded value: +{
+ "description": "Name of the beach (e.g., 'Waikiki', 'Bondi Beach, Sydney'). Auto-geocoded ā provide this or latitude/longitude.",
+ "type": "string"
+}Input schema / properties / latRemoved value: -{
- "type": "number"
-}Input schema / properties / latitudeAdded value: +{
+ "description": "Latitude in decimal degrees (optional if beach_name is given)",
+ "type": "number"
+}Input schema / properties / lonRemoved value: -{
- "type": "number"
-}Input schema / properties / longitudeAdded value: +{
+ "description": "Longitude in decimal degrees (optional if beach_name is given)",
+ "type": "number"
+}Input schema / requiredPrevious value: -[
- "lat",
- "lon"
-]New value: +[]get_uv_forecast6 fields changedInput schema / properties / beach_nameAdded value: +{
+ "description": "Name of the beach (e.g., 'Waikiki', 'Bondi Beach, Sydney'). Auto-geocoded ā provide this or latitude/longitude.",
+ "type": "string"
+}Input schema / properties / latRemoved value: -{
- "type": "number"
-}Input schema / properties / latitudeAdded value: +{
+ "description": "Latitude in decimal degrees (optional if beach_name is given)",
+ "type": "number"
+}Input schema / properties / lonRemoved value: -{
- "type": "number"
-}Input schema / properties / longitudeAdded value: +{
+ "description": "Longitude in decimal degrees (optional if beach_name is given)",
+ "type": "number"
+}Input schema / requiredPrevious value: -[
- "lat",
- "lon"
-]New value: +[]v0.1.0get_beach_jsonget_beach_reportget_surf_forecastget_uv_forecastScored across 4 tools
get_beach_json is explicitly 'the same as get_beach_report but in JSON format,' a pure output-format variant that creates real selection ambiguity, and get_surf_forecast/get_uv_forecast are just filtered slices of get_beach_report. The descriptions do explain when to prefer each one, which keeps it readable but the boundaries are functional rather than distinct.
All four tools follow the same get_<subject> snake_case pattern with no style mixing. The only inconsistency is in the subject convention: two use '<condition>_forecast' while the other two use 'beach_<format/output>'.
Four tools is a reasonable, well-scoped size for a beach-conditions service and nothing feels like filler. It is slightly thin, however, since the surf and UV tools mostly duplicate subsets of the comprehensive report.
The surface covers the core beach-safety read concerns: waves, swell, rip current risk, wind, temperature, UV, and an aggregate safety score, with geocoding handled. Minor gaps remain, such as tide times and water-quality or hazard alerts, which matter for beach safety but are not strictly required.
Weather MCP ā wraps Open-Meteo API (free, no auth)
Open-Meteo MCP ā weather forecast + historical reanalysis + sister APIs
Flood MCP ā wraps Open-Meteo Flood API (free, no auth)
WeatherAPI.com MCP ā wraps WeatherAPI.com (api.weatherapi.com)