Investigate vrc.tl public API + add Timeline tools

[BASIC-BIT]

Background

vrc.tl ("Timeline") is a public, unauthenticated site that aggregates VRChat club events (timeline view, club pages, event detail pages). Since it works without VRChat auth, we can likely integrate it as an optional, read-only data source in this MCP server.

I did a quick Playwright/network pass and confirmed it uses a small set of JSON endpoints under https://vrc.tl/api/v1/.

API endpoints observed (no auth)

• GET https://vrc.tl/api/v1/events

  • Response shape: { lastUpdates, eventData, live, range }
  • range: { firstLoadedDay: "YYYY-MM-DD", lastLoadedDay: "YYYY-MM-DD" } (seems to default to a small window around “now”; query params like from/to and start/end were ignored in my tests)
  • eventData: { events, organizers, performers }
    • events[] item keys (sample): id, name, description, category, tags, organizers, hostOrganizer, start, end, duration, urls, poster, isHighlighted, extensions, promoted, eventSlots, showSlots
    • Important: category is numeric; tags is an array of numeric IDs; event organizers are referenced by numeric IDs.

• GET https://vrc.tl/api/v1/events/{eventId}

  • Response shape: { events, organizers, performers }
  • events is an array (observed events.length === 1) and includes the detailed event object.
  • Event object includes eventSlots[] with per-slot start/duration/performers/flag.

• GET https://vrc.tl/api/v1/organizers

  • Returns an array of organizer/club objects (observed ~852).
  • Keys (sample): id, name, shortCode, slug, vrcGroup, discordInv, twitter, blueSky, instagram, twitch, mixcloud, logo, banner, isSupporter, providesInstances, ...

• GET https://vrc.tl/api/v1/organizer/{organizerId}/events?page={n}

  • Response shape: { page, hasMorePages, data }
  • data: { organizers, events, performers } (dataset pattern again)

• GET https://vrc.tl/api/v1/organizer/{organizerId}/collaborators

  • Response shape: { organizers: [...] }

Proposed MCP tools

Name bikeshed, but roughly:

• vrctl_events_current
  • Calls /api/v1/events
  • Returns compact list of events in the returned range window, with resolved organizer names + key links.
• vrctl_event_get
  • Calls /api/v1/events/{eventId}
  • Returns event details + resolved organizers/performers + slot schedule.
• vrctl_organizers_search
  • Calls /api/v1/organizers (cached), filters by name/slug/shortCode.
  • Returns small summaries + IDs for follow-ups.
• vrctl_organizer_get
  • Uses cached organizers list (or a future /api/v1/organizer/{id} if it exists) and returns details.
• vrctl_organizer_events
  • Calls /api/v1/organizer/{id}/events?page={n}.
• vrctl_organizer_collaborators
  • Calls /api/v1/organizer/{id}/collaborators.

Notes / open questions

• Category + tag ID mapping: API exposes numeric IDs; the website has human labels (Music/Podcast/etc and tags like Windows/Android/flashing lights). We need a mapping strategy:
  • Option A: ship a mapping table (derived from vrc.tl frontend) and keep it updated.
  • Option B: return numeric IDs + “best-effort” labels only for a small stable subset.
• Events range expansion: /api/v1/events appears to return a limited window; need to determine how the site loads more days (if it does) and whether there’s an undocumented endpoint/param for requesting arbitrary ranges.
• Caching: organizers list is large; should be cached with TTL and invalidation.

Acceptance criteria

• New read-only tools added behind a clear namespace/prefix (e.g. vrctl_*).
• Tool outputs are curated (compact lists by default, include IDs for follow-ups).
• Add basic tests (mock responses) to lock response parsing + tool output shape.

[BASIC-BIT]

More detailed planning notes (before code):

Phase 1: High-value read tools

1. vrctl_events_current

• Backing call: GET https://vrc.tl/api/v1/events
• Output contract (curated):
  • range.firstLoadedDay/lastLoadedDay
  • events[]: eventId, name, start/end (ISO + epoch), durationSec, posterUrl, eventUrl
  • organizers[] (resolved): { name, slug, shortCode, vrcGroupUrl, vrchatGroupId? }
  • categoryId (numeric) + optional categoryLabel (best-effort)
  • tagIds[] (numeric) + optional tagLabels[] (best-effort)
  • links from urls when present

2. vrctl_event_get

• Backing call: GET https://vrc.tl/api/v1/events/{eventId}
• Output contract:
  • Above event summary fields
  • description
  • eventSlots[] resolved to performer names:
    • slotId, flag, order, start (ISO + epoch), durationSec, performers[] (names + IDs)

Identifier ergonomics (organizers)

• Recommendation: do NOT require vrc.tl organizer numeric IDs for phase 1 (events tools don’t need them as inputs).
• For any organizer-specific tools later, prefer agent-facing identifiers:
  • VRChat groupId (extract grp_... from vrcGroup URL), and/or shortCode/slug.
  • Use GET /api/v1/organizers (cached) to map groupId|slug|shortCode|name -> organizerId internally.

Unknowns to resolve (research)

• category and tags are numeric IDs; we need a stable mapping strategy:
  • First cut: always return IDs, optionally include labels for known IDs.
  • Later: derive mapping by inspecting frontend bundle constants (no obvious /api/v1/tags or /api/v1/categories endpoints; those 404).
• /api/v1/events returns a limited range window and ignored from/to and start/end params in quick tests.
  • Need to determine how the UI expands the timeline (scroll-triggered reload? hidden params? different endpoint?).

Implementation constraints (vrchat-mcp)

• Keep tools read-only; no VRChat auth required.
• Add caching (short TTL) to reduce repeated hits; include timeouts + clear error messages.
• Ensure tool outputs include IDs needed for follow-ups (eventId, vrchatGroupId when available).

[BASIC-BIT]

More research updates:

Range expansion / paging

The timeline expands its dataset by calling:

• GET https://vrc.tl/api/v1/events?before=YYYY-MM-DD (loads a 3-day chunk ending on that date)
• GET https://vrc.tl/api/v1/events?after=YYYY-MM-DD (loads a 3-day chunk starting on that date)

Example observed:

• /api/v1/events -> range 2026-02-08..2026-02-10 (84 events)
• /api/v1/events?before=2026-02-07 -> range 2026-02-05..2026-02-07 (143 events)
• /api/v1/events?after=2026-02-11 -> range 2026-02-11..2026-02-13 (23 events)

So vrctl_events_current can support arbitrary from/to by paging with before/after and merging/deduping by ID.

Category + tag ID mapping (solves numeric IDs)

The site HTML embeds a window.timeline JSON blob. window.timeline.misc contains authoritative mappings:

• misc.categories[]: { id, name, urlName, icon, description }
• misc.tags[]: { id, name, urlName, group, tooltip, icon, visibleOnEvent, visibleOnFilter, eventsHiddenForNotLoggedIn, tagHiddenForNotLoggedIn }

This is present in GET https://vrc.tl/ HTML (inline <script>window.timeline=...).

Hidden events + auth

Tag metadata includes eventsHiddenForNotLoggedIn / tagHiddenForNotLoggedIn (e.g. NSFW tag). So login can affect visibility.

Login page: https://vrc.tl/login
Providers link to:

• /oauth/discord (redirects to Discord OAuth2 authorize; identify scope)
• /oauth/twitter, /oauth/twitch, /oauth/mixcloud
• /passkey/

Cookies observed for vrc.tl session include PHPSESSID (HttpOnly) and _nss.

Implication: phase-1 tools can be public-only, but we should plan an optional vrc.tl auth flow (cookie jar) for “include hidden events” later.

[BASIC-BIT]

One more detail on hidden events:

• Even when window.timeline.personal.loggedIn === false, GET https://vrc.tl/api/v1/events still returns NSFW-tagged events (tag id 1).
• The website hides them client-side using window.timeline.misc.tags[].eventsHiddenForNotLoggedIn.

So for MCP tool design:

• In public mode, we should filter those events out by default to mirror vrc.tl.
• If we add an includeHidden flag, it should require vrc.tl auth/cookies (or a very explicit override).