Ikuzo
Ikuzo is a map & travel planning app. Access via MCP (JSON-RPC 2.0 over HTTP POST).
Connection
Endpoint: https://ikuzo.app/api/mcp
Auth: Bearer token (from TOOLS.md or user config)
Protocol: JSON-RPC 2.0 — POST with {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"<tool>","arguments":{...}}}
Tools
Maps
maps_list — list all maps (owned + shared)maps_get(mapId) — get map detailsmaps_create(title) — create a new empty map, returns map with ID
Spots
spots_list(mapId, ...) — list/filter spots in a map. Filters: status[], type[], period[], momentFrom/To, text, limit, offset, fields[]spots_get(spotId) — get spot detailsspots_create(mapId, title, gps{lat,lng}, ...) — create spot. Optional: description, type, status, period[], moment{date, repeat, reminder[]}spots_update(spotId, ...) — update any field (including moment, rating)spots_delete(spotId) — soft delete (recoverable)spots_nearby(lat, lng, ...) — find spots near a point across ALL accessible maps. Optional: radius (km, default 10, max 500), mapIds[], all spot filters. Returns sorted by distance.spots_box(north, south, east, west, ...) — find spots in bounding box. Same filters as nearby.
Travel Plans
travels_list — list all travel planstravels_get(travelId) — get plan with stepstravels_create(title) — create plantravels_update(travelId, title) — rename plantravels_delete(travelId) — delete plan
Steps (within a travel plan)
steps_add(travelId, type, ...) — add step. type="spot" requires spotId, type="day" requires title. Optional: orderKeysteps_update(stepId, ...) — update position or titlesteps_delete(stepId) — remove step
Utility
ping — test connectionschema — get valid values for type, status, periodquota — check API usage (doesn't count against quota)
Schema Reference
See references/schema.md for valid spot types, statuses, and periods. Call schema tool at runtime if unsure.
Key Patterns
Find spots to visit nearby
spots_nearby(lat, lng, radius=20, status=["a","b"])
Status a = "Ikuzo!" (priority), b = "To Visit"
Seasonal spots with upcoming moments
spots_list(mapId, momentFrom="2026-03-01", momentTo="2026-04-30")
Create a trip itinerary
travels_create(title) → get travelIdsteps_add(travelId, type="day", title="Day 1 - Arrival")steps_add(travelId, type="spot", spotId="...") for each spot- Repeat day dividers + spots for each day
Efficient listing (reduce tokens)
Use fields to request only what you need:
spots_list(mapId, fields=["_id","title","gps","status","type"])
Image URLs
Spot images use Ikuzo's CDN:
https://ik.offbeatjapan.org/ikuzo/{imageId}.{ext}?tr=h-{height},w-{width}
Where imageId and ext come from the spot's image[] array.
1---2name: ikuzo3description: Manage maps, spots, and travel plans on Ikuzo (ikuzo.app) — a location-based exploration app. Use when creating/editing maps, adding/searching spots, planning trips with day-by-day itineraries, finding nearby places, or managing travel logistics. Triggers on map management, spot tracking, trip planning, location discovery, and "where should I go" questions.4---56# Ikuzo78Ikuzo is a map & travel planning app. Access via MCP (JSON-RPC 2.0 over HTTP POST).910## Connection1112```13Endpoint: https://ikuzo.app/api/mcp14Auth: Bearer token (from TOOLS.md or user config)15Protocol: JSON-RPC 2.0 — POST with {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"<tool>","arguments":{...}}}16```1718## Tools1920### Maps21- `maps_list` — list all maps (owned + shared)22- `maps_get(mapId)` — get map details23- `maps_create(title)` — create a new empty map, returns map with ID2425### Spots26- `spots_list(mapId, ...)` — list/filter spots in a map. Filters: `status[]`, `type[]`, `period[]`, `momentFrom/To`, `text`, `limit`, `offset`, `fields[]`27- `spots_get(spotId)` — get spot details28- `spots_create(mapId, title, gps{lat,lng}, ...)` — create spot. Optional: `description`, `type`, `status`, `period[]`, `moment{date, repeat, reminder[]}`29- `spots_update(spotId, ...)` — update any field (including `moment`, `rating`)30- `spots_delete(spotId)` — soft delete (recoverable)31- **`spots_nearby(lat, lng, ...)`** — find spots near a point across ALL accessible maps. Optional: `radius` (km, default 10, max 500), `mapIds[]`, all spot filters. Returns sorted by distance.32- `spots_box(north, south, east, west, ...)` — find spots in bounding box. Same filters as nearby.3334### Travel Plans35- `travels_list` — list all travel plans36- `travels_get(travelId)` — get plan with steps37- `travels_create(title)` — create plan38- `travels_update(travelId, title)` — rename plan39- `travels_delete(travelId)` — delete plan4041### Steps (within a travel plan)42- `steps_add(travelId, type, ...)` — add step. `type="spot"` requires `spotId`, `type="day"` requires `title`. Optional: `orderKey`43- `steps_update(stepId, ...)` — update position or title44- `steps_delete(stepId)` — remove step4546### Utility47- `ping` — test connection48- `schema` — get valid values for `type`, `status`, `period`49- `quota` — check API usage (doesn't count against quota)5051## Schema Reference5253See `references/schema.md` for valid spot types, statuses, and periods. Call `schema` tool at runtime if unsure.5455## Key Patterns5657### Find spots to visit nearby58```59spots_nearby(lat, lng, radius=20, status=["a","b"])60```61Status `a` = "Ikuzo!" (priority), `b` = "To Visit"6263### Seasonal spots with upcoming moments64```65spots_list(mapId, momentFrom="2026-03-01", momentTo="2026-04-30")66```6768### Create a trip itinerary691. `travels_create(title)` → get travelId702. `steps_add(travelId, type="day", title="Day 1 - Arrival")`713. `steps_add(travelId, type="spot", spotId="...")` for each spot724. Repeat day dividers + spots for each day7374### Efficient listing (reduce tokens)75Use `fields` to request only what you need:76```77spots_list(mapId, fields=["_id","title","gps","status","type"])78```7980### Image URLs81Spot images use Ikuzo's CDN:82```83https://ik.offbeatjapan.org/ikuzo/{imageId}.{ext}?tr=h-{height},w-{width}84```85Where `imageId` and `ext` come from the spot's `image[]` array.
dvcrn