maitabi-mcp-server
Search and retrieve Maitabi mountain-bus and general travel-tour information through read-only tools.
List cascading bus filter options, district/area groups, lodges, styles, and counts.
Search mountain bus tours and lodge packages by month/day, area, style, seat type, keyword, price, and availability.
Fetch detailed bus tour itinerary, pricing, bus stops, and lodging info for one or multiple course numbers.
Search general tours by travel type, keyword, year-month/day, categories, price, sort order, and availability.
Fetch general tour details including itinerary, conditions, price matrix, lodging, departures, and booking links for one or multiple courses.
Fetch monthly departure calendars and schedule matrices for general tours.
All tools return JSON data; no booking or modifying actions are exposed.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@maitabi-mcp-server Search for mountain bus tours departing from Tokyo in August"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Maitabi (Python)
Search Maitabi (まいたび — 毎日新聞旅行 / 毎日あるぺん号) from one package: mountain bus tours (bus.maitabi.jp), general travel and trekking tours, and departure calendars (www.maitabi.jp). It ships as a CLI, an MCP server, and three agent skills — all driven by the same eight actions.
Unofficial client. Not affiliated with 毎日新聞旅行.
Interface | Use it when | Start with |
CLI | you want commands, scripts, or JSON for |
|
MCP server | you want the tools inside an MCP client |
|
Hosted MCP | you want the same tools without installing anything (OAuth) | |
Skills | you want an agent to know the workflows |
|
Install
uv tool install maitabi # installs the `maitabi` command on your PATH
uv tool upgrade maitabi # later, to update it
maitabi --version # confirm which version is runningNothing installed? uvx maitabi ... runs the same published version on demand, e.g. uvx maitabi bus search-tours --month 11.
Related MCP server: MyNextAdventure MCP Server
Quick start (CLI)
# Mountain bus tours
maitabi bus search-tours --month 11 --area 18 --pretty
# General trekking tours
maitabi general search-tours --travel-type 1 --keyword '富士山' --year-month 2026-11
# One tour in full
maitabi bus get-tour-detail --course-no 14241
# Monthly departure matrix
maitabi general get-calendar --year 2026 --month 11 --travel-type 1Every data command accepts --pretty and --output FILE.
Output contract
Search commands return one envelope; every item carries a detail_url:
{
"count": 191,
"page": 1,
"items": [
{
"course_no": 14241,
"course_cd": "S104C21",
"date": "2026年09月12日(土)",
"title": "立山室堂ライン往復ツアー",
"price": "15,500円",
"status": "受付中",
"detail_url": "https://bus.maitabi.jp/detail.html?course_no=14241&year=2026&month=9"
}
],
"query": { "departure": 1, "month": 11, "page": 1 }
}countis the upstream total for the query, before the client-side price/availability filters;itemscan be shorter on the current page.countandpagearenullwhen upstream does not report them;itemsis always a list.Batch detail (
--course-no 14241,8518) returns the same envelope withpage: null; a single course returns the detail object itself.Filter options, district groups, and the calendar return their own objects — a list of one would add indexing without information.
statusis domain-native: a Japanese string for bus, a numeric code for general (1/2 bookable, 3 closed).Errors are always
{"error": ..., "detail": ...}, never a partial envelope.
The contract only grows: new fields appear, existing ones are never renamed or removed within a major version.
Tools (8)
Full parameter reference (MCP args, CLI flags, defaults, endpoints): docs/TOOL_CATALOG.md — generated from the code, so it cannot drift.
Mountain bus (api.bus.maitabi.jp)
MCP tool | CLI | What it does |
|
| filter options, lodges, tour counts (cascading) |
|
| area/district groups + counts |
|
| one master list ( |
|
| search tours and lodge packages |
|
| full itinerary by |
General tours & calendar (www.maitabi.jp)
MCP tool | CLI | What it does |
|
| search by |
|
| itinerary, conditions, every departure + booking link |
|
| monthly departure matrix |
One deliberate exception to "API only"
www.maitabi.jp publishes no tour-detail API — api/v1 serves only category_search and calendar/{year}/{month}, and api.bus.maitabi.jp only knows mountain-bus courses. So general_get_tour_detail reads the rendered detail page, in a way that keeps the fragile surface small:
the tour record itself (title, description, price, statuses) comes from a JSON literal the page embeds (
const detailData = {...}), parsed as JSON — no prose is scraped;only three
<table>elements are read from the markup: itinerary, travel conditions, and the departure/price matrix. Columns are matched by their Japanese headers, not by position.
If the page ever loses that structure the tool returns an error naming source_url instead of a hollow object, and the offline fixtures in tests/fixtures/ fail first.
MCP server
One executable, one subcommand. mcp speaks stdio by default, or sse / streamable-http:
uvx maitabi mcp # stdio — what MCP clients expect
uvx maitabi mcp --transport streamable-http --port 8000
docker run -i --rm phonhay103/maitabi mcp # same thing in a containerClient configuration (mcpServers key):
{
"mcpServers": {
"maitabi": {
"command": "uvx",
"args": ["maitabi", "mcp"]
}
}
}Docker variant:
{
"mcpServers": {
"maitabi": {
"command": "docker",
"args": ["run", "-i", "--rm", "phonhay103/maitabi:latest", "mcp"]
}
}
}Local checkout, no install:
{
"mcpServers": {
"maitabi": {
"command": "uv",
"args": ["run", "--directory", "/path/to/maitabi", "maitabi", "mcp"]
}
}
}Tools are named <domain>_<command>: bus_* reads api.bus.maitabi.jp, general_* reads www.maitabi.jp.
Every tool is read-only (readOnlyHint, idempotentHint, destructiveHint: false), carries a Maitabi: … title, and returns its payload twice: the text block is the same JSON the CLI prints, and structuredContent is that object already parsed. A payload carrying error is reported as isError: true with the retry_hint, so a rate-limited call does not look like an empty result. The server also sends short instructions on initialize: the discovery → search → detail flow, the envelope shape, and the 60 req/min cap on general_*.
See CHANGELOG.md for what changed in each release, and evals/ for the live evaluation suite that checks the tools are usable without the skills.
Gemini (web app)
Add the hosted endpoint as a custom app at https://gemini.google.com/customize/connectors — Gemini runs the OAuth flow itself, so there is no client ID or secret to paste:
Open Customize → Connectors, or Settings → Connected Apps → Custom apps on the older UI. If the "Add a custom app" field is missing, switch the Chat / Spark toggle to Spark first.
Add a custom app, paste
https://maitabi.fastmcp.app/mcp, click Next.Approve the Google Account link, then sign in on the server's OAuth page.
In a Spark chat, type
@and pick the app. Gemini asks permission for each tool call.
Google still limits custom apps to a personal Google Account (not work or school), 18+, US, English, Keep Activity on, and a plan that includes Gemini Spark.
ChatGPT (web app)
Add the hosted endpoint as a plugin at https://chatgpt.com/plugins — the OAuth client registers itself, so any client ID or secret field stays empty:
Open Plugins → + → Add custom MCP server (some accounts still say Create custom MCP server; developer mode is no longer needed).
Name it
Maitabi, then under Connection → Server URL pastehttps://maitabi.fastmcp.app/mcp.Set Authentication → OAuth, tick "I understand and want to continue", and click Create as a plugin. ChatGPT reads the tool list from the server.
Install the plugin, start a chat, type
@and pick it. Each write action asks for confirmation.
Custom MCP servers are created on the web only, and a work workspace can withhold the permission — on Business and Enterprise/Edu an admin owns that switch.
Agent skills
npx skills add phonhay103/maitabi -g # all three
npx skills add phonhay103/maitabi --list # inspect firstmaitabi-cli— terminal workflows and JSON piping.maitabi-mcp— how to call the already-connected tools: which tool, in what order, how to read results.maitabi-bus-extractor— raw HTTP/curl for both hosts, standalone. No CLI, no MCP.
Rate limits
Host | Limit | Applies to |
| 60 requests/min per IP | general tours + calendar |
| none observed at normal usage | mountain bus tours |
When the cap is hit, the result is {"error": "Rate limited by www.maitabi.jp ...", "retry_hint": "wait ~60s and retry manually"}. There is no auto-retry. Narrow --day ranges help, since each day fans out into a parallel request (bounded at 5).
Exit codes
Code | Meaning |
0 | Success |
1 | Upstream/network error (payload contains |
2 | Input error (bad flag value or failed validation) |
Development
make install # uv sync
make dev # MCP server over stdio
make test # offline suite (no network)
make smoke # live check against the production API
make catalog # regenerate docs/TOOL_CATALOG.md + skill reference copies
make catalog-check # what CI runs — fails on stale generated files
make docker-build # 2-stage image (Python 3.14)
make build # wheel + sdistArchitecture, in one paragraph: parameters live once in core/inputs.py; endpoint logic lives in services/; registry.py declares one Action per capability (domain, MCP tool name, CLI command, input model, service, endpoint, docs); both adapters and the catalog are generated from that table, so the CLI, the MCP schema, and the documentation cannot disagree. See AGENTS.md.
Links
Available Tools
7 toolsget_general_tour_detailB
Fetch complete details, itinerary, pricing, and booking information for a general tour on www.maitabi.jp.
Returns a JSON string containing tour itinerary, meal conditions, price matrix, lodging, and booking links.
Inputs: course_no (required). Returns: result
get_tour_calendarA
Fetch monthly departure calendar and tour schedule matrix on www.maitabi.jp for a given year and month.
Returns a JSON string with daily departure schedule matrix, tour availability, and calendar dates.
Inputs: year (required), month (required), travel_type. Returns: result
get_tour_detailA
Fetch detailed information, schedule, pricing, and bus stops for a specific Maitabi mountain bus tour by course_no.
Returns a JSON string containing complete tour itinerary, bus departure points, seat options, pricing, and lodging info.
Inputs: course_no (required). Returns: result
list_district_groupsA
Fetch mountain area/district groups and tour counts for Maitabi mountain bus tours.
Supports cascading filtering—district groups and counts update dynamically based on other selected filters.
Inputs: day, area, month, stay1, +8 more. Returns: result
list_filtersA
Fetch available filter dropdown options, departure areas, tour styles, mountain lodges, and tour counts for Maitabi bus tours.
Supports cascading filtering—options and counts update dynamically based on other selected filters.
Inputs: day, area, month, stay1, +8 more. Returns: result
search_general_toursB
Search general travel tours and mountain climbing packages on www.maitabi.jp.
Returns a JSON string containing matching tours, total count, pagination, sorting, and categories.
Inputs: day, page, keyword, max_price, +10 more. Returns: result
search_toursA
Search mountain bus tours and lodge packages on Maitabi (bus.maitabi.jp) with detailed filter criteria.
Returns a JSON string containing matching bus tours, seat options, pricing, departure dates, and course numbers.
Inputs: day, area, page, month, +12 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
The bus tour vs general tour split is clear, but list_filters and list_district_groups overlap noticeably—both return tour counts and support cascading filters for mountain bus tours. An agent could be unsure which to call when gathering filter options.
All tool names follow a consistent verb_noun snake_case pattern using list_, get_, and search_. The domain distinction is also reflected well with search_tours vs search_general_tours and get_tour_detail vs get_general_tour_detail.
Seven tools is well-scoped for a travel tour search server covering two related subdomains. Each tool has a distinct role, and there is no sense of bloat or excessive fragmentation.
The tool surface covers both main tour types: mountain bus tours and general tours, with search, detail, filters, and calendar data. Minor gaps like the absence of a dedicated general-tour filter listing or a separate mountain-bus calendar are workable given the existing search and calendar tools.
Maintenance
Related MCP Connectors
Ask Japan plus third-party MCP services listed on the Ask Japan hub.
Aggregated travel MCP — flights, tours, activities, price checks, visas, and more.
Read-only MCP for Sparkling Tracks European tours: packages, itineraries, pricing, contacts.
17+ Japan MCP tools (weather/calendar v2/local-pack/enrich). x402 on Base, wallet-free trial.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables managing travel itineraries with CRUD tools for journeys, stops, and plan items, plus weather lookup, integrated with public MCP servers for time and web search.-
- AlicenseAqualityCmaintenanceEnables AI assistants to plan trips in MyNextAdventure by creating trips, managing itineraries, adding flights, hotels, and activities, and sharing results through the MCP protocol.25MIT
- AlicenseNot gradedqualityAmaintenanceEnables MCP-compatible agents to view, create, and edit trip itineraries through conversation, adding places, notes, hotels, transit legs, car rentals, checklists, and budget expenses. Also supports searching places, guides, and hotel deals, plus updating trip dates, day names, and custom sections.302 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables MCP-compatible agents to view and build trip itineraries through conversation, adding places, notes, hotels, transit, checklists, and expenses while managing dates and custom sections.302 npmMIT