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 分