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, and it does disclose meaningful behavior: inputs are auto-geocoded worldwide and either a beach name or raw coordinates may be supplied. It does not mention rate limits, caching, or error behavior for unresolvable beach names, which keeps it short of a 5.
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?
Purpose and returned fields are front-loaded, and the sibling routing is placed last where it reads as a decision aid. The enumeration of output fields is slightly list-heavy but each item is a distinct surf metric, so little is wasted.
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 output schema and no annotations, the description compensates fully by naming the returned metrics and explaining the input resolution strategy. An agent has everything needed to invoke it correctly and interpret the result.
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 three parameters are already fully documented and the baseline is 3. The description reinforces the geocoding behavior with examples ('just say Waikiki or Bondi Beach'), but adds no format or constraint detail beyond the schema.
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 exactly which quantities are returned (wave height/period/direction, swell, rip current risk, safety score). It explicitly distinguishes itself from get_beach_report, so an agent can route without opening the 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 when-to-use condition ('when only surf conditions are needed') paired with the named alternative ('use get_beach_report for the full safety report including wind, temperature, and UV'). The selecting condition and the excluded case are both stated.
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?
No annotations are provided, so the description carries the full burden, and it does well by disclosing the geocoding behavior ('auto-geocoded worldwide'). It also enumerates the returned data fields. It stops short of stating failure modes (e.g., what happens on an unresolvable beach name) or rate limits, which keeps it at 4 rather than 5.
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 sentences, front-loaded with purpose and scope, then input modes, then the sibling routing. Every sentence carries distinct load and none is wasted.
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?
The tool is simple (0 required params, no output schema), and the description covers purpose, inputs, return values, and sibling differentiation. Nothing an agent needs to call it correctly is missing, and the absence of an output schema is compensated by enumerating the returned fields.
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 is 3, but the description adds value by clarifying the two input modes and the auto-geocoding (e.g., "just say 'Waikiki'"), and that providing beach_name or coordinates is sufficient. This is meaningful semantic guidance beyond the raw schema types.
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+resource ('Get the UV index forecast for any beach') and enumerates the returned data: current and max UV index, risk level, and sun-protection recommendations. It also distinguishes itself from the sibling get_beach_report, so an agent can disambiguate immediately.
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 scopes when to use it ('Use this when only sun-exposure info is needed') and names the alternative (get_beach_report) for the broader case. This is exactly the when/when-not/alternative structure that earns a 5.
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.
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_report, get_surf_forecast, and get_uv_forecast have distinct, well-explained scopes with explicit guidance on when to use each. The main ambiguity is get_beach_json vs get_beach_report, which return the same data in different formats, so an agent could trivially misselect between them.
All four tools follow a clean get_<noun>_<format> snake_case pattern (get_beach_json, get_beach_report, get_surf_forecast, get_uv_forecast). Naming is fully predictable and consistent.
Four tightly scoped tools easily fit the beach safety domain, and each earns its place (full report, JSON variant, surf focus, UV focus). No bloat or missing core capability at this count.
Coverage of conditions, surf, and UV is solid for a beach safety surface, but tide tables, water quality, and hazard advisories are absent. These are minor gaps an agent can work around but are relevant for full beach safety.
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)
Marine MCP ā wraps marine-api.open-meteo.com (free, no auth)