Thirdtrail

io.github.thirdtrailPublished by GitHub account thirdtrailv1.0.0Updated Oct 24, 2026

Elevation-corrected sun, moon, twilight, solar and tide data for any point on Earth

VerifiedStreamable HTTPWeb executableLocation & LifestyleData & Analytics

Overview

AI-generated overview

Remote MCP server for elevation-corrected sun, moon, twilight, solar and tide data at any point on Earth.

What you can do
  • Get sunrise, sunset, solar noon, twilight, golden and blue hour, moonrise, moonset and moon phase per day
  • Get Islamic prayer times for a date and location, with school and asr method options
  • Get the sun's position and clear-sky irradiance at one instant, or its sampled path through a day
  • Get clear-sky Daily Light Integral for a date range for crop and greenhouse planning
  • Get tide extremes, tide height series, or a combined tide, sun and moon planning window
When to use it
Useful when an assistant needs to answer timing questions about daylight, darkness, moon phase, prayer schedules, solar siting or coastal tides, especially at a known elevation above sea level. The combined tide window tool suits coastal photography, fishing and shore work planning.
Requirements
A remote streamable HTTP endpoint at thirdtrail.life; no local package needed. Requires a bearer API key in the Authorization header, created on the provider's site. The MCP server requires a paid plan, and a key belongs to one subscription, so it only works with the matching API.
Before you install
The API key is a secret sent in the Authorization header; keep it out of logs and shared configs. The MCP server needs a paid plan, so usage may cost money. Tide heights are relative to mean sea level, not chart datum, exclude weather-driven surge and are not for navigation. Solar path and irradiance data depend on plan tier, and clear-sky values assume cloudless skies.

Installation

In SourceWeft

  1. Open Thirdtrail in the dashboard and add it to a workspace.
  2. Connect Authorization token credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.thirdtrail%2Fthirdtrail/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "thirdtrail": {
      "type": "http",
      "url": "https://thirdtrail.life/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

README

thirdtrail

Python client for the thirdtrail APIs: sun, moon, twilight, solar irradiance and tides for any point on Earth. Sun and moon times are corrected for the elevation you pass in.

bash
pip install thirdtrail
python
from thirdtrail import Client
tt = Client(api_key="tt_live_…")
for day in tt.ephemerides(lat=53.3498, lon=-6.2603, elevation=20):    print(day.date, day.sun.rise, day.sun.set)

Why elevation

Most sunrise APIs answer for an observer standing at sea level. The higher you are, the further you can see, and the earlier the sun clears the horizon.

At the Cliffs of Moher (214 m) the difference is about three minutes, and it moves sunrise, sunset and every golden- and blue-hour boundary with them:

sea levelat 214 m
sunrise07:23:3307:20:25
golden hour, morning start06:56:5106:53:42
moonrise18:03:4817:59:40

Golden hour lasts 20 to 40 minutes, so three minutes is a noticeable share of it. Pass elevation whenever you know it.

What you get

python
day.sun.rise                        # datetime, with its timezone offset intactday.sun.golden_hour.morning.startday.moon.phase.name                 # "Waxing Gibbous"day.moon.phase.illumination         # 0.7376

Timestamps arrive as aware datetime objects, not strings. Anything the client does not model is still available on day.raw and day.response, so you can use a new server-side field before the client catches up.

Endpoints

python
tt.ephemerides(lat=…, lon=…, elevation=…, days=7)     # sun + moon + twilighttt.prayer_times(lat=…, lon=…, school="mwl")           # five daily prayerstt.solar(lat=…, lon=…, timestamp=…)                   # position + irradiancett.solar_path(lat=…, lon=…, interval="5m")            # the sun's arc, sampledtt.solar_dli(lat=…, lon=…, from_date=…, to_date=…)    # Daily Light Integraltt.tide_heights(lat=…, lon=…, step="10m")             # water height seriestt.tide_extremes(lat=…, lon=…)                        # high and low waterstt.tide_window(lat=…, lon=…, elevation=…)             # tides + sun + moontt.tide_constituents(lat=…, lon=…)                    # harmonic constants

Tides take no elevation, with one exception

tide_heights and tide_extremes have no elevation parameter on purpose, because how high you stand doesn't change the ocean surface. If you pass one, you get a TypeError instead of having it silently ignored.

tide_window is the exception, because half of what it returns is sun and moon data:

python
for day in tt.tide_window(lat=52.9715, lon=-9.4309, elevation=214, days=3):    print(day.date, day.sun.golden_hour.morning.start)    for t in day.low_waters:        print("  low water", t.time, t.height_m)

Tide heights are metres relative to mean sea level, not chart datum, and they exclude weather-driven surge. Not for navigation.

Errors

Each kind of failure has its own exception class, so you can catch the one you care about instead of parsing error messages:

python
from thirdtrail import PlanLimitExceeded
try:    tt.tide_extremes(lat=51.5, lon=-2.7, days=90)except PlanLimitExceeded as e:    tt.tide_extremes(lat=51.5, lon=-2.7, days=e.limit)   # e.limit == 31

AuthenticationError (401), PermissionDenied (403, a tier you are not on), PlanLimitExceeded and InvalidRequest (400), RateLimited (429), DataUnavailable (503), ServerError (5xx). All subclass ThirdtrailError.

Transient failures and 429s are retried with backoff. Plan limits are not retried, because the same request would fail the same way every time.

Keys

Create one at thirdtrail.life/apis/keys/. A key belongs to one subscription, so it works with one API; a Tides key calling a solar endpoint gets PermissionDenied.

Every API has a free tier.

Not covered yet

The client doesn't cover the bulk (POST) endpoints, iCalendar feeds or webhook management yet. For those, call the REST API directly; the full contract is published as OpenAPI 3.1.

Using an AI agent? There is an MCP server that exposes the same data as tools.

Licence

MIT

Source: README.md at commit 86611f1

Tools

8

get_sun_moon_times

Sun and moon times

Sunrise, sunset, solar noon, civil, nautical and astronomical twilight, golden and blue hour, moonrise, moonset and moon phase for a location, one entry per day. Use it for any question about when the sun or moon rises, sets or gets dark; for the sun's angle at a given moment use get_solar_position, and for tides alongside the sun use get_tide_window. Pass elevation whenever you know it: it shifts sunrise and sunset at altitude. Defaults: from today, 7 days or the plan's limit if lower. Requires an API key on a paid Ephemerides plan.

Parameterstzlatrequiredlonrequireddayselevationstart_date

get_prayer_times

Islamic prayer times

Fajr, sunrise, dhuhr, asr, maghrib and isha for one date at a location, elevation-corrected. Use it for Islamic prayer schedules; for general sunrise, sunset and twilight use get_sun_moon_times. school is required and sets the fajr and isha rules; asr_method picks the shadow rule and defaults to shafi. date defaults to today. Requires an API key on a paid Ephemerides plan.

Parameterstzlatrequiredlonrequireddateschoolrequiredelevationasr_method

get_solar_position

Solar position and irradiance

The sun's position at one instant: azimuth, altitude, zenith, declination, hour angle and equation of time, plus clear-sky irradiance (GHI, DNI and DHI in W/m²) when include asks for it and the plan covers it. Use it for where the sun is at a given moment; for its track through a whole day use get_solar_path, and for rise and set times use get_sun_moon_times. timestamp defaults to now. Positions are NREL SPA-equivalent on JPL DE421; irradiance comes from the Bird clear-sky model. Requires an API key on a paid Solar plan.

Parameterstzlatrequiredlonrequiredincludeelevationtimestamp

get_solar_path

Solar path for a day

The sun's azimuth and altitude through one UTC day, sampled every interval: a list of timestamped positions. Use it for shading studies, PV siting and panel-angle planning; for a single instant use get_solar_position. date defaults to today and interval to 15m. Requires an API key on a paid Solar plan.

Parameterslatrequiredlonrequireddateintervalelevation

get_daily_light_integral

Daily light integral

Clear-sky Daily Light Integral in mol/m²/day for each day in a range: photosynthetically active radiation integrated from sunrise to sunset. Use it to plan crop growth or supplemental greenhouse lighting; it assumes cloudless skies, so treat it as the ceiling for the site. Pass from and to together for a range of UTC days, or neither for today. Requires an API key on a paid Solar plan.

Parameterstolatrequiredlonrequiredfromelevation

get_tide_extremes

High and low tides

High and low water times and heights at any coastal point, from the FES2022 global tide atlas: a list of events, each with type (high or low), time and height_m. Use it for when high or low tide is; for a continuous curve use get_tide_heights, and for tides together with sunrise, golden hour and moon phase use get_tide_window. Heights are metres relative to MEAN SEA LEVEL, not chart datum — never use for navigation. Defaults: from today, 2 days or the plan's limit if lower. Requires an API key on a paid Tides plan.

Parameterstzlatrequiredlonrequireddaysstart_date

get_tide_heights

Tide height series

Water height at a coastal point at a fixed step: a list of time and height_m pairs. Use it to plot a tide curve or read the height at a particular time; for just the highs and lows use get_tide_extremes. Metres relative to mean sea level, not chart datum. Defaults: from today, 2 days, and the finest step the plan allows, but no finer than 10m. Requires an API key on a paid Tides plan.

Parameterstzlatrequiredlonrequireddaysstepstart_date

get_tide_window

Coastal planning window

Per day: high and low waters together with sunrise, sunset, golden and blue hour, twilight and moon phase in a single call. The planning tool for coastal photography, fishing and shore work; use it instead of calling get_tide_extremes and get_sun_moon_times separately. Pass elevation when you know it: it shifts the sun and moon times — roughly three minutes at clifftop height — but never the tide heights, which do not depend on where the observer stands. Defaults: from today, 2 days or the plan's limit if lower. Requires an API key on a paid Tides plan.

Parameterstzlatrequiredlonrequireddayselevationstart_date

Version history

1
  1. v1.0.0LatestSep 22, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts