Thirdtrail

io.github.thirdtrail由 GitHub 帳號 thirdtrail 發布v1.0.0更新於 Oct 24, 2026

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

已驗證Streamable HTTP可網頁執行位置與生活資料與分析

概覽

AI 產生的概覽

遠端 MCP 伺服器，為地球上任何地點提供經海拔校正的太陽、月亮、晨昏、日照與潮汐資料。

可以做什麼
  • 依日取得日出、日落、太陽正午、晨昏暮光、黃金時刻與藍調時刻、月出月落及月相
  • 依日期與地點取得伊斯蘭教禮拜時間，可選擇教法學派與晡禮計算方式
  • 取得某一時刻的太陽方位與晴空輻照度，或一天內取樣的太陽軌跡
  • 取得日期範圍內的晴空日光積分（DLI），用於作物與溫室補光規劃
  • 取得潮汐極值、潮高序列，或一次呼叫回傳潮汐加日月資訊的規劃視窗
適用情境
適合需要回答日照、天黑時間、月相、禮拜時間、光電選址或海岸潮汐等時間問題的情境，尤其是已知海拔高於海平面的地點。合併的潮汐視窗工具適合海岸攝影、釣魚與岸邊作業規劃。
執行需求
使用 thirdtrail.life 上的遠端 streamable HTTP 端點，不需在本機安裝套件。需要在 Authorization 標頭提供 Bearer API 金鑰，金鑰在服務商網站建立。此 MCP 伺服器需要付費方案，且一把金鑰只屬於一個訂閱，只能呼叫對應的 API。
安裝前請注意
API 金鑰是敏感憑證，透過 Authorization 標頭傳送，請勿寫入日誌或共用設定。此 MCP 伺服器需要付費方案，使用可能產生費用。潮高以平均海平面為基準而非海圖基準，不含天氣造成的暴潮，不可用於導航。太陽軌跡與輻照度資料受方案等級限制，晴空數值假設無雲。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Thirdtrail，將其新增到工作區。
  2. 連接 Authorization token 憑證。它們會被私密儲存，絕不會在公開頁面上展示。
  3. 為需要使用其工具的對話啟用該服務。

Web executable，透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式，或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南，先向你展示發布者、端點和登入方式，經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.thirdtrail%2Fthirdtrail/install.md，並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前，先告訴我它的發布者、端點和登入方式，等我確認。不要把 API 金鑰寫進命令或我會提交的檔案；問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

{
  "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

來源：README.md，提交 86611f1

工具

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.

輸入參數tzlat必填lon必填dayselevationstart_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.

輸入參數tzlat必填lon必填dateschool必填elevationasr_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.

輸入參數tzlat必填lon必填includeelevationtimestamp

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.

輸入參數lat必填lon必填dateintervalelevation

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.

輸入參數tolat必填lon必填fromelevation

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.

輸入參數tzlat必填lon必填daysstart_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.

輸入參數tzlat必填lon必填daysstepstart_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.

輸入參數tzlat必填lon必填dayselevationstart_date

版本歷史

1
  1. v1.0.0最新Sep 22, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分