MCP server
Last updated 18 November 2026
The MCP server puts the Ktemia API inside your editor. You ask for a trip in plain language, the agent looks up the place, runs the search, and reads back each seller’s price with a booking link.
It is a thin layer over https://api.ktemia.com. Same contract, same quota, same errors as calling the HTTP API yourself. Ktemia compares prices; it does not book. The traveller books on the seller’s site.
Published for Node as @ktemia/mcp on npm and for Python as ktemia-mcp on PyPI. Both expose the same seven tools with the same wording and the same behaviour, so pick whichever runtime you already have. Source and issues: Ktemiaa/ktemia-mcp.
What you get
Seven tools, all read-only. Nothing here books, pays, holds, or cancels.
| Tool | Use it for |
|---|---|
ktemia_key_status |
Plan, rate limits, and requests left this month. Costs no quota. |
ktemia_lookup |
Airport, airline, hotel, and car rental location codes |
ktemia_search_flights |
One-way, round trip, and multi-city fares |
ktemia_search_hotels |
Stays, with stars, ratings, and amenity filters |
ktemia_search_cars |
A hire at a city or airport |
ktemia_get_details |
Every price and booking link for one chosen result |
ktemia_get_hotel_reviews |
Guest reviews for one hotel |
Every plan can use it, including Free with its 100 requests a month. A paid plan buys request volume and rate, not access.
Install
You need a key from app.ktemia.com/api-keys. Free, no card.
There is nothing to install by hand. The launcher fetches the package on first run and caches it, so it stays current.
| Runtime | Command | Needs |
|---|---|---|
| Node | npx -y @ktemia/mcp |
Node 20 or newer |
| Python | uvx ktemia-mcp |
Python 3.10 or newer and uv |
The examples below use Node. For Python, swap the command as shown under each client.
Cursor
Add to ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one:
{
"mcpServers": {
"ktemia": {
"command": "npx",
"args": ["-y", "@ktemia/mcp"],
"env": { "KTEMIA_API_KEY": "your-key" }
}
}
}
Python: "command": "uvx" and "args": ["ktemia-mcp"].
Keep the key out of a file you commit. In a project config, read it from the environment with "KTEMIA_API_KEY": "${env:KTEMIA_API_KEY}" instead, and export it in your shell profile.
Claude Code
One command:
claude mcp add ktemia -e KTEMIA_API_KEY=your-key -- npx -y @ktemia/mcp
Python:
claude mcp add ktemia -e KTEMIA_API_KEY=your-key -- uvx ktemia-mcp
Everything after -- is the command Claude Code runs. Check it with claude mcp list.
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%\Claude\claude_desktop_config.json on Windows:
{
"mcpServers": {
"ktemia": {
"command": "npx",
"args": ["-y", "@ktemia/mcp"],
"env": { "KTEMIA_API_KEY": "your-key" }
}
}
}
Python: "command": "uvx" and "args": ["ktemia-mcp"].
Restart Claude Desktop, then ask for a flight.
Claude Desktop starts servers from a GUI process that does not read your shell profile, so npx or uvx must be somewhere it can see. If the server does not start, put the absolute path from which npx or which uvx in command.
Codex CLI
Add to ~/.codex/config.toml:
[mcp_servers.ktemia]
command = "npx"
args = ["-y", "@ktemia/mcp"]
env = { KTEMIA_API_KEY = "your-key" }
Python: command = "uvx" and args = ["ktemia-mcp"].
Any other client
The server speaks MCP over stdio. Run npx -y @ktemia/mcp or uvx ktemia-mcp with KTEMIA_API_KEY in the environment. It negotiates the protocol revision per connection, so it answers both current (2026-07-28) clients and clients that still open with the older initialize handshake.
Check it in a terminal before wiring it into a client:
KTEMIA_API_KEY=your-key npx -y @ktemia/mcp # or: uvx ktemia-mcp
It should sit silently waiting for JSON-RPC on stdin. Ctrl-C to quit. An immediate error means the environment is wrong, and reading it there is easier than digging through a client’s logs.
Try it
Find flights from Lisbon to London on 15 March 2027.
I need a car at Austin airport from 10 to 17 March, automatic, and I am 23.
A hotel in London for two, 10-12 March, four stars or better. Then show me recent reviews for the one I pick.
How many Ktemia requests do I have left this month?
How a search runs
A search is two steps upstream, folded into one tool call.
- The agent calls
ktemia_search_flights(or hotels, or cars) with the trip. It gets a page of results and anextToken. - It calls the same tool again with only
nextTokenfor the next page. WhennextTokenis absent, that was the last page.
Tokens are opaque and expire one hour after the search starts. If one expires, start a new search rather than retrying it.
Hotel and car searches need a location id from ktemia_lookup - the locationId of a result, a numeric string like 29230, not a city name. Flight searches take IATA codes from the code field instead, such as LHR for Heathrow or LON for every London airport.
ktemia_get_details expands one result into every price and booking link. Search pages carry only the leading offers, so this is the call that answers where to actually book.
Quota
Every tool call is one request against the monthly quota, with one exception: ktemia_key_status is free and keeps answering after the quota is spent, which is how an agent diagnoses a QUOTA_EXCEEDED without making it worse.
A search costs at least two requests - one to start it, one per page read - so budget accordingly. The quota is shared across every key on an account, so a second key does not raise the limit.
Two errors both arrive as HTTP 429 and mean opposite things:
| Code | Meaning | What to do |
|---|---|---|
RATE_LIMIT_EXCEEDED |
Too many requests per second | Wait for Retry-After, then retry |
QUOTA_EXCEEDED |
The month’s allowance is gone | Stop. Retrying cannot help. |
Limits per plan are on pricing.
Security
- The key is read from
KTEMIA_API_KEYand sent only as theX-API-Keyheader, over HTTPS, tohttps://api.ktemia.com. - The key is never a tool parameter. An agent should never ask you to paste it into a tool call, and the server never returns it in a result.
- A
KTEMIA_API_URLoverride must behttps://, and redirects are refused, so the key cannot be sent to another host. - Calls carry
X-Ktemia-Client: mcp/<version>, so MCP traffic is separable from direct API traffic in your usage. - Every tool is read-only.
Use a separate key for your editor so you can revoke it without touching a production integration. The quota is per account, so a second key costs nothing in allowance.
Running it yourself
The server is open source. Clone it, build it, and point your client at the build:
git clone https://github.com/Ktemiaa/ktemia-mcp.git
cd ktemia-mcp/typescript
npm install && npm run build
Then use "command": "node" with "args": ["/absolute/path/to/ktemia-mcp/typescript/dist/index.js"].
For the Python implementation, skip the build and use "command": "uv" with "args": ["--directory", "/absolute/path/to/ktemia-mcp/python", "run", "ktemia-mcp"]. Both implementations read one shared contract file, so the tools and their wording cannot drift between them.
What is next
- A hosted server at
mcp.ktemia.com. Not live. Today the server runs locally over stdio, which is why your key stays on your machine and never reaches a Ktemia-hosted MCP endpoint. When the hosted option ships it will be documented here, and the local one will keep working.
Not using MCP?
- Agent skills for Claude Code, Codex, and Cursor run the same searches as skills rather than MCP tools:
/plugin marketplace add Ktemiaa/ktemia-skills, then/plugin install ktemia@ktemia. - AGENTS.md gives a coding agent the whole HTTP contract to call directly.
- The API reference has every field and error, with code in cURL, Python, Node, Go, Java, Ruby, and PHP.