ktemia-mcp 0.1.3__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ktemia_mcp-0.1.3/.gitignore +26 -0
- ktemia_mcp-0.1.3/LICENSE +21 -0
- ktemia_mcp-0.1.3/PKG-INFO +248 -0
- ktemia_mcp-0.1.3/README.md +222 -0
- ktemia_mcp-0.1.3/hatch_build.py +51 -0
- ktemia_mcp-0.1.3/pyproject.toml +71 -0
- ktemia_mcp-0.1.3/scripts/smoke_wheel.py +107 -0
- ktemia_mcp-0.1.3/scripts/sync_spec.py +34 -0
- ktemia_mcp-0.1.3/src/ktemia_mcp/__init__.py +7 -0
- ktemia_mcp-0.1.3/src/ktemia_mcp/__main__.py +30 -0
- ktemia_mcp-0.1.3/src/ktemia_mcp/client.py +263 -0
- ktemia_mcp-0.1.3/src/ktemia_mcp/result.py +113 -0
- ktemia_mcp-0.1.3/src/ktemia_mcp/server.py +502 -0
- ktemia_mcp-0.1.3/src/ktemia_mcp/spec.py +104 -0
- ktemia_mcp-0.1.3/src/ktemia_mcp/tools.json +353 -0
- ktemia_mcp-0.1.3/src/ktemia_mcp/types.py +70 -0
- ktemia_mcp-0.1.3/tests/conftest.py +17 -0
- ktemia_mcp-0.1.3/tests/test_client.py +287 -0
- ktemia_mcp-0.1.3/tests/test_contract.py +170 -0
- ktemia_mcp-0.1.3/tests/test_live.py +209 -0
- ktemia_mcp-0.1.3/tests/test_parity.py +201 -0
- ktemia_mcp-0.1.3/tests/test_tools.py +386 -0
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
node_modules/
|
|
2
|
+
dist/
|
|
3
|
+
*.tsbuildinfo
|
|
4
|
+
|
|
5
|
+
# Python
|
|
6
|
+
__pycache__/
|
|
7
|
+
*.py[cod]
|
|
8
|
+
.venv/
|
|
9
|
+
venv/
|
|
10
|
+
build/
|
|
11
|
+
dist/
|
|
12
|
+
*.egg-info/
|
|
13
|
+
.pytest_cache/
|
|
14
|
+
.ruff_cache/
|
|
15
|
+
uv.lock
|
|
16
|
+
|
|
17
|
+
# Copied in from spec/tools.json during the build by hatch_build.py, and by
|
|
18
|
+
# the test suite's conftest. The original is the tracked one; a committed copy
|
|
19
|
+
# would be a second source of truth that could disagree with it.
|
|
20
|
+
python/src/ktemia_mcp/tools.json
|
|
21
|
+
|
|
22
|
+
.DS_Store
|
|
23
|
+
.env
|
|
24
|
+
.env.local
|
|
25
|
+
|
|
26
|
+
*.local.json
|
ktemia_mcp-0.1.3/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ktemia
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: ktemia-mcp
|
|
3
|
+
Version: 0.1.3
|
|
4
|
+
Summary: Model Context Protocol server for the Ktemia travel search API - flights, hotels, and cars across 100+ providers
|
|
5
|
+
Project-URL: Homepage, https://www.ktemia.com
|
|
6
|
+
Project-URL: Repository, https://github.com/Ktemiaa/ktemia-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/Ktemiaa/ktemia-mcp/issues
|
|
8
|
+
Project-URL: Documentation, https://www.ktemia.com/docs/api/
|
|
9
|
+
Author: Ktemia
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: car-rental,flights,hotels,ktemia,mcp,modelcontextprotocol,travel
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: httpx>=0.27
|
|
24
|
+
Requires-Dist: mcp<3,>=2.3.0
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
# Ktemia MCP server (Python)
|
|
28
|
+
|
|
29
|
+
A [Model Context Protocol](https://modelcontextprotocol.io/) server that searches and compares flights, hotels, and rental cars with the [Ktemia](https://www.ktemia.com/) [API](https://www.ktemia.com/docs/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.
|
|
30
|
+
|
|
31
|
+
Ktemia compares prices. It does not book the ticket, the car, or the room. The traveller books on the seller's site.
|
|
32
|
+
|
|
33
|
+
This is the Python package. A TypeScript package, [`@ktemia/mcp`](https://www.npmjs.com/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.
|
|
34
|
+
|
|
35
|
+
**[Get a free API key](https://app.ktemia.com/api-keys)** · [API reference](https://www.ktemia.com/docs/api/) · [Getting started](https://www.ktemia.com/docs/getting-started/) · [Pricing](https://www.ktemia.com/pricing/) · [Guide: flights in Cursor and Claude](https://www.ktemia.com/blog/flights-mcp/) · [Changelog](https://www.ktemia.com/docs/changelog/)
|
|
36
|
+
|
|
37
|
+
| Tool | Use it for |
|
|
38
|
+
| ---- | ---------- |
|
|
39
|
+
| `ktemia_key_status` | Plan, rate limits, and requests left this month. Costs no quota. |
|
|
40
|
+
| `ktemia_lookup` | Airport, airline, hotel, and car rental location codes |
|
|
41
|
+
| `ktemia_search_flights` | One-way, round trip, and multi-city fares |
|
|
42
|
+
| `ktemia_search_hotels` | Stays, with stars, ratings, and amenity filters |
|
|
43
|
+
| `ktemia_search_cars` | A hire at a city or airport |
|
|
44
|
+
| `ktemia_get_details` | Every price and booking link for one chosen result |
|
|
45
|
+
| `ktemia_get_hotel_reviews` | Guest reviews for one hotel |
|
|
46
|
+
|
|
47
|
+
Every plan can use the MCP server, including the [Free plan](https://www.ktemia.com/pricing/) with its 100 requests a month. A paid plan buys request volume and rate, not access.
|
|
48
|
+
|
|
49
|
+
## Install
|
|
50
|
+
|
|
51
|
+
You need an API key from [app.ktemia.com/api-keys](https://app.ktemia.com/api-keys). Free, no card.
|
|
52
|
+
|
|
53
|
+
You also need [`uv`](https://docs.astral.sh/uv/), which ships `uvx`. `uvx` downloads the package into a throwaway environment and runs it, so there is nothing to install or keep updated:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
brew install uv # macOS
|
|
57
|
+
# or: curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Check it works before wiring it into a client:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
KTEMIA_API_KEY=your-key uvx ktemia-mcp
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
### Cursor
|
|
69
|
+
|
|
70
|
+
Add to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"mcpServers": {
|
|
75
|
+
"ktemia": {
|
|
76
|
+
"command": "uvx",
|
|
77
|
+
"args": ["ktemia-mcp"],
|
|
78
|
+
"env": { "KTEMIA_API_KEY": "${env:KTEMIA_API_KEY}" }
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
`${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:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
export KTEMIA_API_KEY="your-key"
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
To paste the key directly instead, put it in `~/.cursor/mcp.json` rather than a project file, and do not commit it.
|
|
91
|
+
|
|
92
|
+
### Claude Code
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
claude mcp add ktemia -e KTEMIA_API_KEY=your-key -- uvx ktemia-mcp
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Claude Desktop
|
|
99
|
+
|
|
100
|
+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
|
|
101
|
+
|
|
102
|
+
```json
|
|
103
|
+
{
|
|
104
|
+
"mcpServers": {
|
|
105
|
+
"ktemia": {
|
|
106
|
+
"command": "uvx",
|
|
107
|
+
"args": ["ktemia-mcp"],
|
|
108
|
+
"env": { "KTEMIA_API_KEY": "your-key" }
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Restart Claude Desktop, then ask for a flight.
|
|
115
|
+
|
|
116
|
+
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`.
|
|
117
|
+
|
|
118
|
+
### Codex CLI
|
|
119
|
+
|
|
120
|
+
Add to `~/.codex/config.toml`:
|
|
121
|
+
|
|
122
|
+
```toml
|
|
123
|
+
[mcp_servers.ktemia]
|
|
124
|
+
command = "uvx"
|
|
125
|
+
args = ["ktemia-mcp"]
|
|
126
|
+
env = { KTEMIA_API_KEY = "your-key" }
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Any other MCP client
|
|
130
|
+
|
|
131
|
+
The server speaks MCP over stdio. Run `uvx ktemia-mcp` with `KTEMIA_API_KEY` in the environment.
|
|
132
|
+
|
|
133
|
+
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.
|
|
134
|
+
|
|
135
|
+
### Without uv
|
|
136
|
+
|
|
137
|
+
`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:
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
pip install ktemia-mcp
|
|
141
|
+
which ktemia-mcp # use this as "command"
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Try it
|
|
145
|
+
|
|
146
|
+
> Find flights from Lisbon to London on 15 March 2027.
|
|
147
|
+
|
|
148
|
+
> I need a car at Austin airport from 10 to 17 March, automatic, and I am 23.
|
|
149
|
+
|
|
150
|
+
> 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.
|
|
151
|
+
|
|
152
|
+
> How many Ktemia requests do I have left this month?
|
|
153
|
+
|
|
154
|
+
## How the search tools work
|
|
155
|
+
|
|
156
|
+
A search is two steps upstream, folded into one tool call:
|
|
157
|
+
|
|
158
|
+
1. Call `ktemia_search_flights` (or hotels, or cars) with the trip details. You get the first page of results and a `nextToken`.
|
|
159
|
+
2. Call the **same tool** again with only `nextToken` to get the next page. When `nextToken` is absent, that was the last page.
|
|
160
|
+
|
|
161
|
+
Tokens are opaque and expire **one hour** after the search starts. If a token expires, start a new search rather than retrying it.
|
|
162
|
+
|
|
163
|
+
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.
|
|
164
|
+
|
|
165
|
+
`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".
|
|
166
|
+
|
|
167
|
+
## Quota
|
|
168
|
+
|
|
169
|
+
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.
|
|
170
|
+
|
|
171
|
+
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.
|
|
172
|
+
|
|
173
|
+
Two different errors both arrive as HTTP 429, and they mean opposite things:
|
|
174
|
+
|
|
175
|
+
| Code | Meaning | What to do |
|
|
176
|
+
| ---- | ------- | ---------- |
|
|
177
|
+
| `RATE_LIMIT_EXCEEDED` | Too many requests per second | Wait for `Retry-After`, then retry |
|
|
178
|
+
| `QUOTA_EXCEEDED` | The month's allowance is gone | Stop. Retrying cannot help. |
|
|
179
|
+
|
|
180
|
+
Limits per plan are on [pricing](https://www.ktemia.com/pricing/).
|
|
181
|
+
|
|
182
|
+
## Security
|
|
183
|
+
|
|
184
|
+
- The key is read from `KTEMIA_API_KEY` and sent only as the `X-API-Key` header, over HTTPS, to `https://api.ktemia.com`.
|
|
185
|
+
- 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.
|
|
186
|
+
- 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.
|
|
187
|
+
- Upstream calls carry `X-Ktemia-Client: mcp/<version>`, so MCP traffic is distinguishable from direct API traffic in Ktemia's own logs.
|
|
188
|
+
- Every tool is read-only. Nothing here books, pays, holds, or cancels anything.
|
|
189
|
+
|
|
190
|
+
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.
|
|
191
|
+
|
|
192
|
+
## Use it as a library
|
|
193
|
+
|
|
194
|
+
The client is importable, so the error mapping is reusable outside MCP:
|
|
195
|
+
|
|
196
|
+
```python
|
|
197
|
+
import asyncio
|
|
198
|
+
from ktemia_mcp import KtemiaClient, KtemiaError
|
|
199
|
+
|
|
200
|
+
async def main():
|
|
201
|
+
client = KtemiaClient() # reads KTEMIA_API_KEY
|
|
202
|
+
try:
|
|
203
|
+
print(await client.get("/key"))
|
|
204
|
+
except KtemiaError as error:
|
|
205
|
+
print(error.code, error.retryable, error.message)
|
|
206
|
+
|
|
207
|
+
asyncio.run(main())
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
## Self-host
|
|
211
|
+
|
|
212
|
+
The server is open source: [github.com/Ktemiaa/ktemia-mcp](https://github.com/Ktemiaa/ktemia-mcp).
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
git clone https://github.com/Ktemiaa/ktemia-mcp.git
|
|
216
|
+
cd ktemia-mcp/python
|
|
217
|
+
uv sync
|
|
218
|
+
uv run pytest
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Then point your client at `uv --directory /path/to/ktemia-mcp/python run ktemia-mcp`.
|
|
222
|
+
|
|
223
|
+
## Learn more
|
|
224
|
+
|
|
225
|
+
**Docs**
|
|
226
|
+
|
|
227
|
+
- [Travel API reference](https://www.ktemia.com/docs/api/) — every field and error, with code in cURL, Python, Node, Go, Java, Ruby, and PHP
|
|
228
|
+
- [Key status and quota](https://www.ktemia.com/docs/api/key/) · [Getting started](https://www.ktemia.com/docs/getting-started/) · [Changelog](https://www.ktemia.com/docs/changelog/)
|
|
229
|
+
- [Flights](https://www.ktemia.com/docs/api/flights/search/) · [Hotels](https://www.ktemia.com/docs/api/hotels/search/) · [Cars](https://www.ktemia.com/docs/api/cars/search/)
|
|
230
|
+
|
|
231
|
+
**For agents and tools**
|
|
232
|
+
|
|
233
|
+
- [OpenAPI 3.1 spec](https://www.ktemia.com/openapi.json) · [AGENTS.md](https://www.ktemia.com/AGENTS.md) · [llms.txt](https://www.ktemia.com/llms.txt)
|
|
234
|
+
- [Ktemia skills](https://github.com/Ktemiaa/ktemia-skills) for Claude Code, Codex, and Cursor — the same searches as agent skills rather than MCP tools
|
|
235
|
+
- [Public Postman collection](https://www.postman.com/ktemia-411711/ktemia-api/overview)
|
|
236
|
+
|
|
237
|
+
**Guides**
|
|
238
|
+
|
|
239
|
+
- [Flights in Cursor and Claude: MCP, skills, and instructions](https://www.ktemia.com/blog/flights-mcp/)
|
|
240
|
+
- [Best travel API in 2026](https://www.ktemia.com/blog/best-travel-api/)
|
|
241
|
+
|
|
242
|
+
## About Ktemia
|
|
243
|
+
|
|
244
|
+
[Ktemia](https://www.ktemia.com/) 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](https://www.ktemia.com/product/), through the [API](https://www.ktemia.com/docs/api/), or with the AI copilot.
|
|
245
|
+
|
|
246
|
+
## License
|
|
247
|
+
|
|
248
|
+
MIT
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
# Ktemia MCP server (Python)
|
|
2
|
+
|
|
3
|
+
A [Model Context Protocol](https://modelcontextprotocol.io/) server that searches and compares flights, hotels, and rental cars with the [Ktemia](https://www.ktemia.com/) [API](https://www.ktemia.com/docs/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.
|
|
4
|
+
|
|
5
|
+
Ktemia compares prices. It does not book the ticket, the car, or the room. The traveller books on the seller's site.
|
|
6
|
+
|
|
7
|
+
This is the Python package. A TypeScript package, [`@ktemia/mcp`](https://www.npmjs.com/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.
|
|
8
|
+
|
|
9
|
+
**[Get a free API key](https://app.ktemia.com/api-keys)** · [API reference](https://www.ktemia.com/docs/api/) · [Getting started](https://www.ktemia.com/docs/getting-started/) · [Pricing](https://www.ktemia.com/pricing/) · [Guide: flights in Cursor and Claude](https://www.ktemia.com/blog/flights-mcp/) · [Changelog](https://www.ktemia.com/docs/changelog/)
|
|
10
|
+
|
|
11
|
+
| Tool | Use it for |
|
|
12
|
+
| ---- | ---------- |
|
|
13
|
+
| `ktemia_key_status` | Plan, rate limits, and requests left this month. Costs no quota. |
|
|
14
|
+
| `ktemia_lookup` | Airport, airline, hotel, and car rental location codes |
|
|
15
|
+
| `ktemia_search_flights` | One-way, round trip, and multi-city fares |
|
|
16
|
+
| `ktemia_search_hotels` | Stays, with stars, ratings, and amenity filters |
|
|
17
|
+
| `ktemia_search_cars` | A hire at a city or airport |
|
|
18
|
+
| `ktemia_get_details` | Every price and booking link for one chosen result |
|
|
19
|
+
| `ktemia_get_hotel_reviews` | Guest reviews for one hotel |
|
|
20
|
+
|
|
21
|
+
Every plan can use the MCP server, including the [Free plan](https://www.ktemia.com/pricing/) with its 100 requests a month. A paid plan buys request volume and rate, not access.
|
|
22
|
+
|
|
23
|
+
## Install
|
|
24
|
+
|
|
25
|
+
You need an API key from [app.ktemia.com/api-keys](https://app.ktemia.com/api-keys). Free, no card.
|
|
26
|
+
|
|
27
|
+
You also need [`uv`](https://docs.astral.sh/uv/), which ships `uvx`. `uvx` downloads the package into a throwaway environment and runs it, so there is nothing to install or keep updated:
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
brew install uv # macOS
|
|
31
|
+
# or: curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Check it works before wiring it into a client:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
KTEMIA_API_KEY=your-key uvx ktemia-mcp
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
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.
|
|
41
|
+
|
|
42
|
+
### Cursor
|
|
43
|
+
|
|
44
|
+
Add to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"mcpServers": {
|
|
49
|
+
"ktemia": {
|
|
50
|
+
"command": "uvx",
|
|
51
|
+
"args": ["ktemia-mcp"],
|
|
52
|
+
"env": { "KTEMIA_API_KEY": "${env:KTEMIA_API_KEY}" }
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`${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:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
export KTEMIA_API_KEY="your-key"
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
To paste the key directly instead, put it in `~/.cursor/mcp.json` rather than a project file, and do not commit it.
|
|
65
|
+
|
|
66
|
+
### Claude Code
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
claude mcp add ktemia -e KTEMIA_API_KEY=your-key -- uvx ktemia-mcp
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Claude Desktop
|
|
73
|
+
|
|
74
|
+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows:
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"mcpServers": {
|
|
79
|
+
"ktemia": {
|
|
80
|
+
"command": "uvx",
|
|
81
|
+
"args": ["ktemia-mcp"],
|
|
82
|
+
"env": { "KTEMIA_API_KEY": "your-key" }
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
Restart Claude Desktop, then ask for a flight.
|
|
89
|
+
|
|
90
|
+
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`.
|
|
91
|
+
|
|
92
|
+
### Codex CLI
|
|
93
|
+
|
|
94
|
+
Add to `~/.codex/config.toml`:
|
|
95
|
+
|
|
96
|
+
```toml
|
|
97
|
+
[mcp_servers.ktemia]
|
|
98
|
+
command = "uvx"
|
|
99
|
+
args = ["ktemia-mcp"]
|
|
100
|
+
env = { KTEMIA_API_KEY = "your-key" }
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
### Any other MCP client
|
|
104
|
+
|
|
105
|
+
The server speaks MCP over stdio. Run `uvx ktemia-mcp` with `KTEMIA_API_KEY` in the environment.
|
|
106
|
+
|
|
107
|
+
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.
|
|
108
|
+
|
|
109
|
+
### Without uv
|
|
110
|
+
|
|
111
|
+
`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:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
pip install ktemia-mcp
|
|
115
|
+
which ktemia-mcp # use this as "command"
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
## Try it
|
|
119
|
+
|
|
120
|
+
> Find flights from Lisbon to London on 15 March 2027.
|
|
121
|
+
|
|
122
|
+
> I need a car at Austin airport from 10 to 17 March, automatic, and I am 23.
|
|
123
|
+
|
|
124
|
+
> 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.
|
|
125
|
+
|
|
126
|
+
> How many Ktemia requests do I have left this month?
|
|
127
|
+
|
|
128
|
+
## How the search tools work
|
|
129
|
+
|
|
130
|
+
A search is two steps upstream, folded into one tool call:
|
|
131
|
+
|
|
132
|
+
1. Call `ktemia_search_flights` (or hotels, or cars) with the trip details. You get the first page of results and a `nextToken`.
|
|
133
|
+
2. Call the **same tool** again with only `nextToken` to get the next page. When `nextToken` is absent, that was the last page.
|
|
134
|
+
|
|
135
|
+
Tokens are opaque and expire **one hour** after the search starts. If a token expires, start a new search rather than retrying it.
|
|
136
|
+
|
|
137
|
+
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.
|
|
138
|
+
|
|
139
|
+
`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".
|
|
140
|
+
|
|
141
|
+
## Quota
|
|
142
|
+
|
|
143
|
+
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.
|
|
144
|
+
|
|
145
|
+
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.
|
|
146
|
+
|
|
147
|
+
Two different errors both arrive as HTTP 429, and they mean opposite things:
|
|
148
|
+
|
|
149
|
+
| Code | Meaning | What to do |
|
|
150
|
+
| ---- | ------- | ---------- |
|
|
151
|
+
| `RATE_LIMIT_EXCEEDED` | Too many requests per second | Wait for `Retry-After`, then retry |
|
|
152
|
+
| `QUOTA_EXCEEDED` | The month's allowance is gone | Stop. Retrying cannot help. |
|
|
153
|
+
|
|
154
|
+
Limits per plan are on [pricing](https://www.ktemia.com/pricing/).
|
|
155
|
+
|
|
156
|
+
## Security
|
|
157
|
+
|
|
158
|
+
- The key is read from `KTEMIA_API_KEY` and sent only as the `X-API-Key` header, over HTTPS, to `https://api.ktemia.com`.
|
|
159
|
+
- 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.
|
|
160
|
+
- 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.
|
|
161
|
+
- Upstream calls carry `X-Ktemia-Client: mcp/<version>`, so MCP traffic is distinguishable from direct API traffic in Ktemia's own logs.
|
|
162
|
+
- Every tool is read-only. Nothing here books, pays, holds, or cancels anything.
|
|
163
|
+
|
|
164
|
+
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.
|
|
165
|
+
|
|
166
|
+
## Use it as a library
|
|
167
|
+
|
|
168
|
+
The client is importable, so the error mapping is reusable outside MCP:
|
|
169
|
+
|
|
170
|
+
```python
|
|
171
|
+
import asyncio
|
|
172
|
+
from ktemia_mcp import KtemiaClient, KtemiaError
|
|
173
|
+
|
|
174
|
+
async def main():
|
|
175
|
+
client = KtemiaClient() # reads KTEMIA_API_KEY
|
|
176
|
+
try:
|
|
177
|
+
print(await client.get("/key"))
|
|
178
|
+
except KtemiaError as error:
|
|
179
|
+
print(error.code, error.retryable, error.message)
|
|
180
|
+
|
|
181
|
+
asyncio.run(main())
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## Self-host
|
|
185
|
+
|
|
186
|
+
The server is open source: [github.com/Ktemiaa/ktemia-mcp](https://github.com/Ktemiaa/ktemia-mcp).
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
git clone https://github.com/Ktemiaa/ktemia-mcp.git
|
|
190
|
+
cd ktemia-mcp/python
|
|
191
|
+
uv sync
|
|
192
|
+
uv run pytest
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Then point your client at `uv --directory /path/to/ktemia-mcp/python run ktemia-mcp`.
|
|
196
|
+
|
|
197
|
+
## Learn more
|
|
198
|
+
|
|
199
|
+
**Docs**
|
|
200
|
+
|
|
201
|
+
- [Travel API reference](https://www.ktemia.com/docs/api/) — every field and error, with code in cURL, Python, Node, Go, Java, Ruby, and PHP
|
|
202
|
+
- [Key status and quota](https://www.ktemia.com/docs/api/key/) · [Getting started](https://www.ktemia.com/docs/getting-started/) · [Changelog](https://www.ktemia.com/docs/changelog/)
|
|
203
|
+
- [Flights](https://www.ktemia.com/docs/api/flights/search/) · [Hotels](https://www.ktemia.com/docs/api/hotels/search/) · [Cars](https://www.ktemia.com/docs/api/cars/search/)
|
|
204
|
+
|
|
205
|
+
**For agents and tools**
|
|
206
|
+
|
|
207
|
+
- [OpenAPI 3.1 spec](https://www.ktemia.com/openapi.json) · [AGENTS.md](https://www.ktemia.com/AGENTS.md) · [llms.txt](https://www.ktemia.com/llms.txt)
|
|
208
|
+
- [Ktemia skills](https://github.com/Ktemiaa/ktemia-skills) for Claude Code, Codex, and Cursor — the same searches as agent skills rather than MCP tools
|
|
209
|
+
- [Public Postman collection](https://www.postman.com/ktemia-411711/ktemia-api/overview)
|
|
210
|
+
|
|
211
|
+
**Guides**
|
|
212
|
+
|
|
213
|
+
- [Flights in Cursor and Claude: MCP, skills, and instructions](https://www.ktemia.com/blog/flights-mcp/)
|
|
214
|
+
- [Best travel API in 2026](https://www.ktemia.com/blog/best-travel-api/)
|
|
215
|
+
|
|
216
|
+
## About Ktemia
|
|
217
|
+
|
|
218
|
+
[Ktemia](https://www.ktemia.com/) 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](https://www.ktemia.com/product/), through the [API](https://www.ktemia.com/docs/api/), or with the AI copilot.
|
|
219
|
+
|
|
220
|
+
## License
|
|
221
|
+
|
|
222
|
+
MIT
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""Build hook that copies the shared tool spec into the package.
|
|
2
|
+
|
|
3
|
+
``spec/tools.json`` lives at the repository root so both the TypeScript and
|
|
4
|
+
Python packages read one file, and it is deliberately not committed inside
|
|
5
|
+
``src/`` - a second copy under version control is a second source of truth that
|
|
6
|
+
can disagree with the first.
|
|
7
|
+
|
|
8
|
+
That leaves a chicken-and-egg problem: a wheel cannot include a file from
|
|
9
|
+
outside its project directory, so the file must be copied in before the build,
|
|
10
|
+
but anything that builds the package (``uv sync``, ``pip install -e .``) runs
|
|
11
|
+
the build first. Doing the copy here, inside the build itself, is what breaks
|
|
12
|
+
the cycle: a fresh clone installs with no manual step.
|
|
13
|
+
|
|
14
|
+
Building from an sdist has no repository root above it. That is fine, because
|
|
15
|
+
the sdist already contains the copy this hook made when the sdist was built; in
|
|
16
|
+
that case the hook verifies rather than copies.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import shutil
|
|
22
|
+
from pathlib import Path
|
|
23
|
+
from typing import Any
|
|
24
|
+
|
|
25
|
+
from hatchling.builders.hooks.plugin.interface import BuildHookInterface
|
|
26
|
+
|
|
27
|
+
TARGET = Path("src") / "ktemia_mcp" / "tools.json"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class SpecBuildHook(BuildHookInterface):
|
|
31
|
+
PLUGIN_NAME = "ktemia-spec"
|
|
32
|
+
|
|
33
|
+
def initialize(self, version: str, build_data: dict[str, Any]) -> None:
|
|
34
|
+
root = Path(self.root)
|
|
35
|
+
target = root / TARGET
|
|
36
|
+
source = root.parent / "spec" / "tools.json"
|
|
37
|
+
|
|
38
|
+
if source.is_file():
|
|
39
|
+
target.parent.mkdir(parents=True, exist_ok=True)
|
|
40
|
+
shutil.copyfile(source, target)
|
|
41
|
+
return
|
|
42
|
+
|
|
43
|
+
# No repository root: this is a build from an sdist, which ships the
|
|
44
|
+
# copy already. If it is missing too, fail loudly now rather than
|
|
45
|
+
# shipping a server that cannot start.
|
|
46
|
+
if not target.is_file():
|
|
47
|
+
raise FileNotFoundError(
|
|
48
|
+
f"Neither {source} nor {target} exists, so the shared tool "
|
|
49
|
+
"spec cannot be packaged. Build from a full checkout of "
|
|
50
|
+
"https://github.com/Ktemiaa/ktemia-mcp."
|
|
51
|
+
)
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "ktemia-mcp"
|
|
3
|
+
version = "0.1.3"
|
|
4
|
+
description = "Model Context Protocol server for the Ktemia travel search API - flights, hotels, and cars across 100+ providers"
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "MIT"
|
|
7
|
+
authors = [{ name = "Ktemia" }]
|
|
8
|
+
requires-python = ">=3.10"
|
|
9
|
+
keywords = ["mcp", "modelcontextprotocol", "ktemia", "travel", "flights", "hotels", "car-rental"]
|
|
10
|
+
classifiers = [
|
|
11
|
+
"Development Status :: 4 - Beta",
|
|
12
|
+
"Intended Audience :: Developers",
|
|
13
|
+
"License :: OSI Approved :: MIT License",
|
|
14
|
+
"Programming Language :: Python :: 3",
|
|
15
|
+
"Programming Language :: Python :: 3.10",
|
|
16
|
+
"Programming Language :: Python :: 3.11",
|
|
17
|
+
"Programming Language :: Python :: 3.12",
|
|
18
|
+
"Programming Language :: Python :: 3.13",
|
|
19
|
+
"Topic :: Software Development :: Libraries",
|
|
20
|
+
]
|
|
21
|
+
dependencies = [
|
|
22
|
+
# 2.x renamed FastMCP to MCPServer; the 1.x API does not work here.
|
|
23
|
+
"mcp>=2.3.0,<3",
|
|
24
|
+
"httpx>=0.27",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[project.urls]
|
|
28
|
+
Homepage = "https://www.ktemia.com"
|
|
29
|
+
Repository = "https://github.com/Ktemiaa/ktemia-mcp"
|
|
30
|
+
Issues = "https://github.com/Ktemiaa/ktemia-mcp/issues"
|
|
31
|
+
Documentation = "https://www.ktemia.com/docs/api/"
|
|
32
|
+
|
|
33
|
+
[project.scripts]
|
|
34
|
+
ktemia-mcp = "ktemia_mcp.__main__:main"
|
|
35
|
+
|
|
36
|
+
[dependency-groups]
|
|
37
|
+
dev = ["pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.8"]
|
|
38
|
+
|
|
39
|
+
[build-system]
|
|
40
|
+
requires = ["hatchling"]
|
|
41
|
+
build-backend = "hatchling.build"
|
|
42
|
+
|
|
43
|
+
[tool.hatch.build.targets.wheel]
|
|
44
|
+
packages = ["src/ktemia_mcp"]
|
|
45
|
+
|
|
46
|
+
# The shared tool contract lives at the repository root so both packages read
|
|
47
|
+
# one file, and it is not committed inside src/. hatch_build.py copies it in
|
|
48
|
+
# during the build, which is what lets a fresh clone install with no manual
|
|
49
|
+
# step; see the module docstring there.
|
|
50
|
+
[tool.hatch.build.hooks.custom]
|
|
51
|
+
path = "hatch_build.py"
|
|
52
|
+
|
|
53
|
+
[tool.hatch.build.targets.wheel.force-include]
|
|
54
|
+
"src/ktemia_mcp/tools.json" = "ktemia_mcp/tools.json"
|
|
55
|
+
|
|
56
|
+
# The sdist carries the copied spec, so a build from the sdist alone works
|
|
57
|
+
# without a repository root above it.
|
|
58
|
+
[tool.hatch.build.targets.sdist]
|
|
59
|
+
include = ["src", "tests", "scripts", "hatch_build.py", "README.md", "LICENSE"]
|
|
60
|
+
|
|
61
|
+
[tool.pytest.ini_options]
|
|
62
|
+
asyncio_mode = "auto"
|
|
63
|
+
asyncio_default_fixture_loop_scope = "function"
|
|
64
|
+
testpaths = ["tests"]
|
|
65
|
+
|
|
66
|
+
[tool.ruff]
|
|
67
|
+
line-length = 100
|
|
68
|
+
target-version = "py310"
|
|
69
|
+
|
|
70
|
+
[tool.ruff.lint]
|
|
71
|
+
select = ["E", "F", "I", "UP", "B"]
|