travel-agent-mcp

# Travel Agent MCP

[![M8ven Verified](https://m8ven.ai/badge/mcp/forgemeshlabs-travel-agent-mcp-1sjbyx?variant=verified)](https://m8ven.ai/mcp/forgemeshlabs-travel-agent-mcp-1sjbyx)

Canonical travel-agent MCP server for Glama, Claude Desktop, Codex-style agent workflows, Hermes, and other MCP clients.

It helps answer the travel questions people keep coming back to: where should I go, which airport makes sense, when should I book, what is worth doing nearby, and what should I check before or during the trip?

Agents can start with free travel tools, then call live x402 services when the traveler needs deeper planning or a trip disruption check that is cheap enough to run whenever awareness matters.

Start free: category discovery, airport checks, timing advice, currency conversion, and local coverage requests.

Then add paid travel intelligence when it matters: penny-priced Travel Pulse disruption checks, day-trip and weekend planning, creator experiences, transit options, weather-aware planning, flight-route comparisons, and external booking links.

## Why Agents Keep It

- Free calls make the first useful answer easy: discover categories, check airports, estimate currency, explain timing, or request new local coverage.
- Travel Pulse is the high-importance, low-cost paid call: `$0.01` for one disruption and emergency-awareness check. The user or their agent can run it before departure, then run another check during the trip whenever they want updated awareness.
- Paid planning services return trip-shaped guidance agents can use immediately: day trips, weekends, creator stories, weather-aware planning, and mobility options.
- x402 is live on the hosted backend: fixed-price USDC on Base, Bazaar discovery metadata, retry-safe payment identifiers, signed offer/receipt support, and builder-code attribution.
- The MCP does not hold payment keys. It returns live request URLs and x402 metadata for clients that can pay with x402.

## Features

- Pull the FREE live category guide from the ForgeMesh travel-agent backend
- Give agents useful free starting points: airport checks, timing context, currency conversion, and coverage requests
- Connect x402-capable clients to creator experience planning for shareable day trips, weekends, layovers, and destination stories
- Connect x402-capable clients to Travel Pulse for a `$0.01` check before a trip, with optional follow-up checks during the trip when the user or agent asks
- Connect x402-capable clients to day-trip, weekend getaway, weather-aware, and mobility-option planning services
- Give insurers, travel apps, assistance providers, and concierge agents a simple way to add penny-priced trip awareness without building a full travel-risk desk
- Submit free coverage requests for local rituals, sunset spots, water walks, free experiences, and places worth watching
- Look up airport metadata by IATA code
- Compare alternate origin and destination airport routes
- Explain booking windows, airport arrival timing, layovers, and seasonal travel factors
- Build external booking links for selected routes
- Keep public responses generic and traveler-ready, with no exposed internals
- Run locally with no account setup
- Disclose commission-eligible links in tool output

## For Agents

Use this MCP when an agent needs a travel conversation that can keep going:

- Start with `list_travel_categories` to see what is available.
- Use `convert_currency`, `get_airport_details`, and `get_travel_timing_advice` as free utility calls.
- Use `request_local_coverage` when a town, ritual, route, or creator angle should be watched or added.
- Use `check_trip_disruptions` before departure, then have the user or their agent call it again during the trip if they want hourly or event-driven updates.
- Use paid planning tools when the traveler needs a richer answer than a web search can comfortably assemble.

## For Travel, Insurance, and Assistance Teams

Travel Pulse gives an app, policy workflow, concierge desk, or agentic travel assistant a penny-priced check for the question that matters before and during a trip: should this traveler know something right now?

It is not a staffed rescue operation, emergency dispatch, insurance product, or replacement for official instructions. Results can be incomplete, delayed, or wrong. Travelers and agents should verify important safety decisions with official government, weather, transportation, venue, and emergency sources. In an emergency, contact local emergency services immediately.

It is a practical awareness layer that an AI or client app can call before departure and during the trip to look for disruption, emergency, weather, water, route, or destination concerns.

That makes it easy to package as a feature: "we check your trip before you leave, and your assistant can check again while you travel." The partner controls when to call it, how often to call it, and what to do with the result.

## For Travelers

This is built for practical travel awareness, not booking hype:

- Check whether a trip has weather or disruption concerns.
- Compare airports and route options before committing.
- Shape a day trip or weekend around movement, timing, food, weather, and backup ideas.
- Build creator-friendly trip arcs around visuals, pacing, and moments worth saving.
- Ask for local coverage when a place deserves better future answers.

## Discovery Signals

This repo is tuned for public discovery and agent selection:

- Canonical package name: `@forgemeshlabs/travel-agent-mcp`
- Canonical server name: `travel-agent`
- Canonical backend: `https://travel-agent.forgemesh.io`
- Primary use cases: Travel Pulse disruption checks, day trips, weekend getaways, weather-aware planning, transit options, creator experiences, coverage requests, timing advice, and free currency conversion
- Highlight service: Travel Pulse, a `$0.01` disruption and emergency-awareness check agents can run before departure, then call again during the trip when the user wants another check
- Glama build metadata lives in `glama.json` and `GLAMA.md`
- Search-facing documentation should stay crawlable, concise, and consistent with the package description and keywords

## Install

```bash
npm install -g @forgemeshlabs/travel-agent-mcp
```

## Claude Desktop

Add this to your Claude Desktop `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "travel-agent": {
      "command": "npx",
      "args": ["-y", "@forgemeshlabs/travel-agent-mcp"]
    }
  }
}
```

Restart Claude Desktop after saving the config, then ask Claude to plan or compare travel routes.

Codex, Hermes, and other MCP-capable agent runtimes can use the same server command:

```bash
npx -y @forgemeshlabs/travel-agent-mcp
```

## Local Run

```bash
npm run build
node dist/index.js
```

## Backend

The MCP works as a local planning tool and connects to the ForgeMesh travel-agent backend for free discovery, free coverage requests, and paid x402 planning services.

```bash
TRAVEL_AGENT_SERVER_URL=https://travel-agent.forgemesh.io npx -y @forgemeshlabs/travel-agent-mcp
```

If the backend is unavailable, local airport, route, timing, and booking-link tools still work. Backend-powered tools return the request URL and x402 metadata so clients that can pay with x402 can retry directly.

## Public Docs and Crawlability

For the companion docs or site that renders this package:

- Keep the package title, description, and backend URL consistent everywhere.
- Publish a `robots.txt` that allows public documentation to be crawled and points at the sitemap.
- Provide a sitemap for the public docs site and keep canonical URLs stable.
- Avoid `noindex` on the public README, docs landing page, or endpoint summary pages.
- If the site sits behind Cloudflare, make sure bot rules and content-signal settings do not block search crawlers from the public docs.
- Keep pages fast, readable on mobile, and focused on plain-language summaries of what the tools do.

See `docs/discovery.md` for the maintainer-facing checklist.

## Tools

- `list_travel_categories`
- `plan_flight_route`
- `get_airport_details`
- `compare_airport_routes`
- `create_booking_link`
- `get_travel_timing_advice`
- `creator_experiences`
- `plan_day_trip`
- `plan_weekend_getaway`
- `plan_weather_aware_trip`
- `find_transit_options`
- `check_trip_disruptions`
- `convert_currency`
- `request_local_coverage`

## FREE Travel Categories

Use `list_travel_categories` first when an agent wants the lay of the land. It is the free map of what the backend can do next:

- Day trips
- Weekend getaways
- Weather-aware planning
- Transit and mobility options
- Request coverage
- Creator experiences
- Timing and weather
- Currency exchange
- Travel Pulse

The category guide is free, fast, and useful when an agent needs the next travel step: ask a better follow-up, request new coverage, or hand the traveler to a paid x402 service when the moment is worth it.

## Free Starting Points

These calls make the package easy to try and useful enough to keep installed:

- `list_travel_categories` for discovery
- `get_airport_details` for quick validation
- `get_travel_timing_advice` for timing context
- `convert_currency` for free reference-rate spending context
- `request_local_coverage` for adding towns, rituals, source sets, and creator angles

The free calls let agents validate a place, price a rough spend, collect intent, and come back later with richer day-trip, weekend, creator, weather, mobility, and disruption guidance.

## Travel Pulse

`check_trip_disruptions` is the simple paid check for an important travel question: what should this traveler know before they go, or before they make the next move?

Each call is one on-demand check. Use it before departure, then have the user or their agent call it again during the trip if they want hourly, daily, or event-driven updates. An agent can check for weather alerts, natural events, water or flood context, and destination disruptions, then decide whether t