Mardi Gras FYI

Mardi Gras FYI for developers

A free, read-only API and MCP server for New Orleans (Orleans Parish) Carnival parade schedules, routes, krewes and local advice. No key needed.

Dates and times are local to New Orleans (America/Chicago). A parade’s time is when it departs the start of its route; it reaches any other block later. Follow live progress on Routewise. Every parade includes a citation link to its mardigras.fyi page. Please credit “Mardi Gras FYI” with a link when you show this data.

REST API

Base URL https://mardigras.fyi/api/v1. The OpenAPI 3.1 document (https://mardigras.fyi/api/openapi.json) describes every parameter and schema.

RequestReturns
GET /parades?year=2027&date=2027-02-05Parades by year, date, start_date/end_date, period, area or q (name)
GET /parades/{event_id}One parade with its profile
GET /parades/{event_id}/routeRoute as a GeoJSON Feature
GET /parades/nearby?lat=29.9266&lon=-90.102&within_hours=2Parades near a point by departure window
GET /streets/parades?street=Napoleon&cross_street=St.%20CharlesParades on a street or through a corner
GET /krewes, /krewes/{name}Krewes and krewe details
GET /seasons/2027Carnival start, parade weekends and Mardi Gras day
GET /guide?query=bathroomsLocal advice articles
GET /score?street=Napoleon&cross_street=St.%20Charles&dates=2027-02-06Carnival Score for a corner, address or lat/lon, for the season or chosen nights
GET /score/compare?at=29.93,-90.10&at=Canal%20%26%20CarrolltonCompare two to six places
GET /score/gridThe scored hex grid for the season and each parade day (JSON)

curl

curl "https://mardigras.fyi/api/v1/streets/parades?year=2027&street=Napoleon&cross_street=St.%20Charles"

JavaScript

const response = await fetch("https://mardigras.fyi/api/v1/parades?year=2027&period=second_weekend");
const {data, meta} = await response.json();
for (const parade of data) console.log(parade.date, parade.timeLabel, parade.name, parade.citation.url);

Python

import requests

r = requests.get("https://mardigras.fyi/api/v1/parades/nearby",
                 params={"lat": 29.9266, "lon": -90.102, "from": "2027-02-05T17:00", "within_hours": 2})
r.raise_for_status()
for parade in r.json()["data"]["departingInWindow"]:
    print(parade["name"], "departs in", parade["minutesUntilDeparture"], "minutes")

Responses

Successful responses are {"data": …, "meta": {"apiVersion": "1", "attribution": …, "timezone": "America/Chicago", "generatedAt": …}}. Each parade carries citation and provenance; provenance is null until source verification details are published for that record. Parades without a route map are listed under unmapped in street and nearby results: whether they pass is unknown, not “no”.

Location privacy

/parades/nearby takes coordinates because your application supplies them for its own users. They are used only to answer that request: Mardi Gras FYI does not store or log them, and responses are not tied to a user. Requests pass through Cloudflare, which hosts the service. The MCP server never asks for coordinates. Its nearby tool takes a street corner instead.

Errors

Errors use one shape, {"error": {"code", "message", "details"?, "docs"}}, and are never cached.

StatusCodeMeaning
400invalid_parameterA parameter is missing or malformed; details lists each one
404not_foundUnknown parade, krewe, path, or streets that do not meet
404street_not_foundNo New Orleans street matches; details.suggestions may help
409ambiguous_intersectionThe names meet at more than one corner; details.candidates lists each with full street names
405method_not_allowedThe API is read-only
429rate_limitedToo many requests; wait Retry-After seconds
503service_unavailableTemporary failure; retry shortly

Rate limits, caching and CORS

Each client address may make 120 requests per 60 seconds. Over the limit you receive 429 with a Retry-After header. Data responses are cacheable for five minutes (one minute for “now” queries). All responses allow cross-origin requests from any site.

Calendar feeds

Subscribable iCalendar feeds, refreshed every six hours by most clients: /calendar/2027.ics (the season), /calendar/2027/{first-weekend|second-weekend|mardi-gras-day}.ics, and /calendar/parade/{event_id}.ics. UIDs match the /api/calendar downloads, so updates replace events rather than duplicating them. Untimed parades are date-only. Times are New Orleans departures.

To show upcoming parades or one parade on your own site, use the embeddable widget.

MCP server

Streamable HTTP endpoint: https://mardigras.fyi/mcp. Read-only, no sign-in, no user data. Connect it to an assistant so its answers come from this calendar.

Claude

In Claude, open Settings → Connectors, choose Add custom connector and enter https://mardigras.fyi/mcp. In Claude Code:

claude mcp add --transport http mardi-gras https://mardigras.fyi/mcp

ChatGPT

Turn on developer mode in ChatGPT settings (under Apps → Advanced settings), then create an app with the MCP server URL https://mardigras.fyi/mcp and no authentication. Availability depends on your ChatGPT plan.

Cursor

Add the server to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "mardi-gras": { "url": "https://mardigras.fyi/mcp" }
  }
}

Tools

ToolUse
find_eventsParades by year, single date, date range, weekend, area or name
get_eventOne parade by event_id
find_parades_on_streetParades running along a street, or passing a corner with cross_street
find_parades_near_intersectionParades near a corner that depart within a time window
get_kreweKrewe profile, traditions, permit figures and parades by year
get_parade_routeRoute GeoJSON and route points for walking links
search_carnival_guideLocal advice: kids, arrival, restrooms, rideshares, crossing, throws, weather, trackers
export_calendariCalendar file for selected parades
get_walking_directionsGoogle Maps walking link to a point on the route
get_carnival_scoreCarnival Score for an address, corner or coordinates, optionally for chosen nights
compare_locationsTwo to six places to stay compared side by side

Questions or corrections: contact us.