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---5
6# Ikuzo
7
8Ikuzo is a map & travel planning app. Access via MCP (JSON-RPC 2.0 over HTTP POST).
9
10## Connection
11
12```
13Endpoint: https://ikuzo.app/api/mcp
14Auth: 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```
17
18## Tools
19
20### Maps
21- `maps_list` — list all maps (owned + shared)
22- `maps_get(mapId)` — get map details
23- `maps_create(title)` — create a new empty map, returns map with ID
24
25### Spots
26- `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 details
28- `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.
33
34### Travel Plans
35- `travels_list` — list all travel plans
36- `travels_get(travelId)` — get plan with steps
37- `travels_create(title)` — create plan
38- `travels_update(travelId, title)` — rename plan
39- `travels_delete(travelId)` — delete plan
40
41### 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 title
44- `steps_delete(stepId)` — remove step
45
46### Utility
47- `ping` — test connection
48- `schema` — get valid values for `type`, `status`, `period`
49- `quota` — check API usage (doesn't count against quota)
50
51## Schema Reference
52
53See `references/schema.md` for valid spot types, statuses, and periods. Call `schema` tool at runtime if unsure.
54
55## Key Patterns
56
57### Find spots to visit nearby
58```
59spots_nearby(lat, lng, radius=20, status=["a","b"])
60```
61Status `a` = "Ikuzo!" (priority), `b` = "To Visit"
62
63### Seasonal spots with upcoming moments
64```
65spots_list(mapId, momentFrom="2026-03-01", momentTo="2026-04-30")
66```
67
68### Create a trip itinerary
691. `travels_create(title)` → get travelId
702. `steps_add(travelId, type="day", title="Day 1 - Arrival")`
713. `steps_add(travelId, type="spot", spotId="...")` for each spot
724. Repeat day dividers + spots for each day
73
74### Efficient listing (reduce tokens)
75Use `fields` to request only what you need:
76```
77spots_list(mapId, fields=["_id","title","gps","status","type"])
78```
79
80### Image URLs
81Spot 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.
modbender