Skip to main content
Glama
matheusgalvao1

Travel Planner MCP Server

by matheusgalvao1
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

Travel Planner MCP Server

Minimal TypeScript MCP server for a personal travel-planning agent.

Agent-visible tools:

  • search_flights — real flight options from Google Flights (via SerpApi)

  • search_hotels — real hotel/rental options from Google Hotels (via SerpApi)

Web search is intentionally excluded so it can be handled by your LLM provider's built-in web/search tool. The intended flow:

User
  -> LLM travel agent
    -> built-in web search for destination facts
    -> travel-planner.search_flights for real flight options
    -> travel-planner.search_hotels for real hotel options
  -> LLM compares tradeoffs and produces the recommendation

Design

Adapter (src/providers)    = talks to SerpApi
Normalizer (src/normalizers) = translates SerpApi response into our product shape
LLM                        = reasons over our product shape

A single SerpApi key powers both engines. The server is a thin wrapper: no booking, payments, itineraries, ranking, or post-booking support — the LLM composes the plan from the structured results.

Related MCP server: MCP-TS-DEMO

Install

npm install

Run in mock mode (no API key needed)

npm run mock        # TRAVEL_MCP_MOCK=1, returns realistic mock data

Develop / build (live)

cp .env.example .env   # set SERPAPI_API_KEY
npm run dev            # tsx, live
npm run build && npm start

Test

npm test               # input validation, normalizers, provider errors, tool shapes

MCP client config example

{
  "mcpServers": {
    "travel-planner": {
      "command": "node",
      "args": ["/absolute/path/to/travel-planner-mcp/build/index.js"],
      "env": {
        "SERPAPI_API_KEY": "your_serpapi_key",
        "DEFAULT_CURRENCY": "BRL",
        "DEFAULT_MARKET": "BR",
        "DEFAULT_LOCALE": "pt-BR"
      }
    }
  }
}

Set TRAVEL_MCP_MOCK=1 in env to run the client against mock data.

Environment variables

Variable

Required

Notes

SERPAPI_API_KEY

live mode

SerpApi key for both engines

SERPAPI_BASE_URL

no

defaults to https://serpapi.com/search.json

DEFAULT_CURRENCY

no

e.g. BRL, USD

DEFAULT_MARKET

no

Google gl country code, e.g. BR

DEFAULT_LOCALE

no

Google hl language code, e.g. pt-BR

REQUEST_TIMEOUT_MS

no

supplier call timeout, default 15000

TRAVEL_MCP_MOCK

no

1 to use mock data instead of SerpApi

Notes

Supplier-specific request building is isolated in src/providers/* (serpapi.ts is the shared client), and SerpApi → product-shape mapping lives in src/normalizers/*. Flight/hotel result shapes are FlightOption / HotelOption.

Available Tools

2 tools
search_flightsA

Search real flight options from Google Flights (via SerpApi). Use this for flight inventory, prices, carriers, durations, stops, and booking links. Only recommend flights returned by this tool; do not invent flights.

ParametersJSON Schema
NameRequiredDescriptionDefault
originYesOrigin IATA airport/city code, e.g. GRU, SAO, JFK
destinationYesDestination IATA airport/city code, e.g. GIG, RIO, LIS
departure_dateYesYYYY-MM-DD
return_dateNoYYYY-MM-DD for round trips; omit for one-way
passengersNo
cabinNoeconomy
constraintsNo
currencyNoBRL
marketNoCountry code (Google `gl`), e.g. BR, USBR
localeNoLanguage code (Google `hl`), e.g. pt-BR, enpt-BR
result_limitNo

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only states what the tool does but omits details on rate limits, pagination, data freshness, or error handling. The result_limit parameter exists but is not mentioned in terms of behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise—two sentences that front-load the purpose and a critical usage constraint. No superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 11 parameters and no output schema, the description lacks completeness. It lists types of returned info but does not describe output structure, pagination, error handling, or how constraints affect results, leaving the agent with uncertainties.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 55% (moderate). The description adds no parameter-specific meaning beyond what the schema already provides. Baseline score of 3 is appropriate given coverage and lack of additional param info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Search real flight options') and explicitly lists the types of information returned (flight inventory, prices, carriers, durations, stops, booking links). It clearly distinguishes from the sibling tool 'search_hotels'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage context (searching real flights) and includes an important constraint ('Only recommend flights returned by this tool; do not invent flights'). However, it lacks explicit guidance on when not to use it or alternatives beyond the obvious sibling differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_hotelsA

Search real hotel/accommodation options from Google Hotels (via SerpApi). Use this for hotel inventory, nightly/total prices, ratings, hotel class, amenities, coordinates, and booking links. Only recommend hotels returned by this tool; do not invent hotels.

ParametersJSON Schema
NameRequiredDescriptionDefault
destinationYesFree-text destination: city, region, neighborhood, or property name
check_inYesYYYY-MM-DD
check_outYesYYYY-MM-DD
guestsNo
budgetNo
constraintsNo
currencyNoBRL
marketNoCountry code (Google `gl`), e.g. BR, USBR
localeNoLanguage code (Google `hl`), e.g. pt-BR, enpt-BR
result_limitNo

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description must carry full burden. Mentions real options and source, but omits behavioral details like rate limits, data freshness, or that results are from a third-party API. Insufficient for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, each with clear purpose: first states what the tool does and its source, second provides usage constraint. No wasted words, front-loaded with critical info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has 10 parameters, no output schema, and no annotations. Description lists available data types but does not cover output format, pagination, default sorting, or error handling. For a complex search tool, this is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 50%, but description adds no parameter-specific meaning beyond 'hotel inventory, prices, ratings'. It does not elaborate on how parameters like budget, constraints, or result_limit affect the search. The description's value for parameters is minimal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb 'search' with resource 'real hotel/accommodation options from Google Hotels via SerpApi'. Clearly distinguishes from sibling 'search_flights'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to use for hotel inventory and to only recommend results from this tool, providing clear usage context. Does not mention alternatives or when not to use, but sibling tool implies domain separation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedsearch_flights
    • First observedsearch_hotels
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool targets a distinct domain (flights vs. hotels) with no overlap, making it clear which to use for each purpose.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (search_flights, search_hotels), providing predictability and clarity.

Tool Count3/5

With only 2 tools, the server feels thin for a 'Travel Planner'—search alone is insufficient for planning beyond information retrieval.

Completeness2/5

The server only offers search functionality, lacking critical operations like booking, itinerary management, or destination recommendations, which are essential for a full travel planner.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • metasearch-mcp

    YeonwooSung
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for using various search tools like Tavily API. Planning to support various search tools (i.e. wiki search, searxng, etc)
    3
    MIT

  • MCP-TS-DEMO

    pjqdyd
    A
    license
    D
    quality
    D
    maintenance
    A TypeScript MCP server demo supporting local Stdio and remote Streamable HTTP, demonstrating tool invocation for AI agents.
    2
    MIT

  • MCP Server

    imanelmzk
    F
    license
    Not graded
    quality
    F
    maintenance
    A basic MCP server implementation using Node.js and TypeScript that bridges AI models with external tools and data sources via JSON-RPC.
    2
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/matheusgalvao1/travel-planner-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server