MCP reference

timer.ly publishes a JSON-RPC 2.0 MCP server at POST https://www.timer.ly/api/mcp. Below is the auto-generated tool catalog. Add a server entry to your MCP-aware client with no auth and no extra configuration — every tool is anonymous.

Endpoint

POST https://www.timer.ly/api/mcp
Content-Type: application/json

Methods

initialize — handshake; returns server info + protocolVersion: 2024-11-05.
tools/list — returns the tools below.
tools/call — invoke a tool. Params: { name, arguments }.
ping — liveness check, returns {}.

Tools

`build_duration_url`

Build a timer.ly countdown URL for a duration. Combine days, hours, minutes, and seconds (at least one must be > 0). Returns a shareable URL the recipient can open to see a live countdown that reaches zero.

Input schema

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "minimum": 0,
      "description": "Whole days (0–3650)."
    },
    "hours": {
      "type": "integer",
      "minimum": 0,
      "description": "Whole hours."
    },
    "minutes": {
      "type": "integer",
      "minimum": 0,
      "description": "Whole minutes."
    },
    "seconds": {
      "type": "integer",
      "minimum": 0,
      "description": "Whole seconds."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "de",
        "fr",
        "es",
        "it"
      ],
      "description": "Output locale for the URL prefix (default en)."
    }
  },
  "additionalProperties": false
}

`build_target_url`

Build a countdown URL to a future instant. Accepts ISO 8601 with timezone (`2026-12-25T15:00:00Z`, `2026-12-25T15:00-05:00`, `2026-12-25T15:00-pst`) or date-only (`2026-12-25`). Returns a shareable URL.

Input schema

{
  "type": "object",
  "required": [
    "iso"
  ],
  "properties": {
    "iso": {
      "type": "string",
      "description": "ISO 8601 date or datetime. Accepts trailing tz suffix (e.g. -pst, -cet)."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "de",
        "fr",
        "es",
        "it"
      ]
    }
  },
  "additionalProperties": false
}

`build_since_url`

Build a count-up URL from a past instant. Same ISO grammar as build_target_url, but the past date must be within the last 100 years. Returns a URL that shows "time elapsed since".

Input schema

{
  "type": "object",
  "required": [
    "iso"
  ],
  "properties": {
    "iso": {
      "type": "string"
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "de",
        "fr",
        "es",
        "it"
      ]
    }
  },
  "additionalProperties": false
}

`build_event_url`

Build a countdown URL for a curated event (christmas, new_year, easter, summer_solstice, winter_solstice). Returns the canonical locale-aware URL plus the next occurrence date. Use list_curated_events to enumerate.

Input schema

{
  "type": "object",
  "required": [
    "event"
  ],
  "properties": {
    "event": {
      "type": "string",
      "enum": [
        "christmas",
        "new_year",
        "easter",
        "summer_solstice",
        "winter_solstice"
      ],
      "description": "Event id. Hyphenated forms (new-year, summer-solstice) are also accepted."
    },
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "de",
        "fr",
        "es",
        "it"
      ]
    }
  },
  "additionalProperties": false
}

`list_curated_events`

List the curated cross-locale events that timer.ly knows about, with each one's next-occurrence date and the locale-specific URL. Use to enumerate the catalog before calling build_event_url.

Input schema

{
  "type": "object",
  "properties": {
    "locale": {
      "type": "string",
      "enum": [
        "en",
        "de",
        "fr",
        "es",
        "it"
      ]
    }
  },
  "additionalProperties": false
}

`list_holidays`

List national / bank / federal holidays for a country in a date range. Each entry includes a stable slug and the canonical /to/{slug} URL. Defaults: next 12 months from today.

Input schema

{
  "type": "object",
  "required": [
    "country"
  ],
  "properties": {
    "country": {
      "type": "string",
      "enum": [
        "uk",
        "us",
        "de",
        "fr",
        "es",
        "it"
      ]
    },
    "from": {
      "type": "string",
      "description": "ISO date YYYY-MM-DD (inclusive). Default: today."
    },
    "to": {
      "type": "string",
      "description": "ISO date YYYY-MM-DD (inclusive). Default: today + 365 days."
    }
  },
  "additionalProperties": false
}

`parse_countdown_url`

Reverse-parse a timer.ly URL. Identifies the countdown kind (duration / target / since / event) and returns the encoded payload. Useful for round-tripping URLs an agent has previously generated or received.

Input schema

{
  "type": "object",
  "required": [
    "url"
  ],
  "properties": {
    "url": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Example

curl -s -X POST https://www.timer.ly/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"list_holidays",
                 "arguments":{"country":"de"}}}'