Skip to main content

Ktemia MCP server (Python)

A Model Context Protocol server that searches and compares flights, hotels, and rental cars with the Ktemia API. Point Cursor, Claude Code, Claude Desktop, Codex, or any MCP client at it, ask in plain language, and the agent looks up the place, runs the search, and returns each seller's price with a booking link.

Ktemia compares prices. It does not book the ticket, the car, or the room. The traveller books on the seller's site.

This is the Python package. A TypeScript package, @ktemia/mcp, exposes the same seven tools with the same descriptions and the same behaviour — both read one shared contract file, so pick whichever runtime you already have.

Get a free API key · API reference · Getting started · Pricing · Guide: flights in Cursor and Claude · Changelog

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 the MCP server, including the Free plan with its 100 requests a month. A paid plan buys request volume and rate, not access.

Install

You need an API key from app.ktemia.com/api-keys. Free, no card.

You also need uv, which ships uvx. uvx downloads the package into a throwaway environment and runs it, so there is nothing to install or keep updated:

brew install uv          # macOS
# or: curl -LsSf https://astral.sh/uv/install.sh | sh

Check it works before wiring it into a client:

KTEMIA_API_KEY=your-key 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 fixing it here is easier than through a client's logs.

Cursor

Add to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "ktemia": {
      "command": "uvx",
      "args": ["ktemia-mcp"],
      "env": { "KTEMIA_API_KEY": "${env:KTEMIA_API_KEY}" }
    }
  }
}

${env:KTEMIA_API_KEY} reads the key from your shell environment, so the key itself is not committed in a project file. Export it in your shell profile:

export KTEMIA_API_KEY="your-key"

To paste the key directly instead, put it in ~/.cursor/mcp.json rather than a project file, and do not commit it.

Claude Code

claude mcp add ktemia -e KTEMIA_API_KEY=your-key -- uvx ktemia-mcp

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": "uvx",
      "args": ["ktemia-mcp"],
      "env": { "KTEMIA_API_KEY": "your-key" }
    }
  }
}

Restart Claude Desktop, then ask for a flight.

Claude Desktop launches servers from a GUI process that does not read your shell profile, so uvx must be on a system path it can see. If the server fails to start, use the absolute path from which uvx as command.

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.ktemia]
command = "uvx"
args = ["ktemia-mcp"]
env = { KTEMIA_API_KEY = "your-key" }

Any other MCP client

The server speaks MCP over stdio. Run 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.

Without uv

pipx run ktemia-mcp works the same way. Or install it into an environment you control and use the absolute path to the installed script, which avoids a per-launch resolution step:

pip install ktemia-mcp
which ktemia-mcp      # use this as "command"

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, free cancellation if you can find it. Then show me recent reviews for the one I pick.

How many Ktemia requests do I have left this month?

How the search tools work

A search is two steps upstream, folded into one tool call:

  1. Call ktemia_search_flights (or hotels, or cars) with the trip details. You get the first page of results and a nextToken.
  2. Call the same tool again with only nextToken to get the next page. When nextToken is absent, that was the last page.

Tokens are opaque and expire one hour after the search starts. If a token expires, start a new search rather than retrying it.

Hotel and car searches need a location id from ktemia_lookup — the locationId field of a result, which is 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 do I actually book this".

Quota

Every tool call is one request against your plan's 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 error 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 creating a second key does not raise the limit.

Two different errors both arrive as HTTP 429, and they 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_KEY and sent only as the X-API-Key header, over HTTPS, to https://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 exposes it in a result.
  • A KTEMIA_API_URL override must be https:// (or localhost, for development), and redirects are refused, so the key cannot be sent to another host.
  • Upstream calls carry X-Ktemia-Client: mcp/<version>, so MCP traffic is distinguishable from direct API traffic in Ktemia's own logs.
  • Every tool is read-only. Nothing here books, pays, holds, or cancels anything.

Consider using 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 you nothing in allowance.

Use it as a library

The client is importable, so the error mapping is reusable outside MCP:

import asyncio
from ktemia_mcp import KtemiaClient, KtemiaError

async def main():
    client = KtemiaClient()  # reads KTEMIA_API_KEY
    try:
        print(await client.get("/key"))
    except KtemiaError as error:
        print(error.code, error.retryable, error.message)

asyncio.run(main())

Self-host

The server is open source: github.com/Ktemiaa/ktemia-mcp.

git clone https://github.com/Ktemiaa/ktemia-mcp.git
cd ktemia-mcp/python
uv sync
uv run pytest

Then point your client at uv --directory /path/to/ktemia-mcp/python run ktemia-mcp.

Learn more

Docs

For agents and tools

Guides

About Ktemia

Ktemia is a search and compare platform for flights, hotels, car rentals, and real estate. Flights, hotels, and cars are live in the API; real estate is next. Use it in the dashboard, through the API, or with the AI copilot.

License

MIT

Metadata

Release files for ktemia-mcp 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ktemia-mcp 0.1.4
File Size Uploaded Provenance Actions
ktemia_mcp-0.1.4.tar.gz 36.5 kB With provenance Details for ktemia_mcp-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ktemia-mcp 0.1.4
File Interpreter ABI Platform Actions
ktemia_mcp-0.1.4-py3-none-any.whl Python 3 none any Details for ktemia_mcp-0.1.4-py3-none-any.whl

Total release size: 61.9 kB

Release files / ktemia_mcp-0.1.4.tar.gz

Download URL ktemia_mcp-0.1.4.tar.gz
Size 36.5 kB
Tags Source
SHA-256 checksum
How to use checksums
0381893ba28451e2009eee1831c44fbacc2704969e6d5b76e6349bb9116ce52c
BLAKE2b-256 checksum
How to use checksums
168c7c94821700293c5eb15e88f53d64d9aaa2ae8f9662a47366741a28487988
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / ktemia_mcp-0.1.4-py3-none-any.whl

Download URL ktemia_mcp-0.1.4-py3-none-any.whl
Size 25.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cd793fc7020af50bd8356f38e317f1c5c73b803bedd57074b8e7ad870e584453
BLAKE2b-256 checksum
How to use checksums
f0d89ee17d43c9fd26c121139683c1aaae96ceb778d34bf411a6904daa95bd0e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for ktemia-mcp 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ktemia_mcp-0.1.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.4 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page