mcp-tellus-search

mcp-tellus-search

A Model Context Protocol (MCP) server that exposes Skyscanner's Tellus (Travel API v2) to Claude.

---

What is MCP?

MCP (Model Context Protocol) is a protocol that lets Claude call external tools. This project packages Tellus API functions as MCP tools so Claude can search geo entities (cities, airports, hotels, etc.) directly during a conversation.

When Claude is connected to this MCP server, it can:

• Look up entities by ID
• Search entities by type or location
• Fetch child entities of a parent (e.g. all hotels in a city)
• Find nearby entities by radius
• Get suggested airports for a city

---

How it works

Architecture

Claude Code
    │
    │  stdio (JSON messages)
    ▼
Docker Container  ←── mcp.run() blocks here, waiting for requests
    │
    └── python src/server.py
            │
            └── FastMCP registers all @mcp.tool() functions
                    │
                    └── requests → Tellus API (gateway.skyscanner.net)

Key concepts

• @mcp.tool() decorator registers a function as an MCP tool. Claude sees the function name, docstring, and type annotations — it never sees the raw source code.
• mcp.run() starts the server and blocks, listening on stdin. The container stays alive for the entire Claude session (one container per session).
• The container is started automatically by Claude Code when it reads .mcp.json, and destroyed on exit (--rm).

---

Project structure

.
├── Dockerfile          # Packages the server into a Docker image
├── .mcp.json           # Tells Claude Code how to launch the server
├── requirements.txt    # Python dependencies installed inside the image
└── src/
    └── server.py       # MCP tools + Tellus API helper functions

---

Available tools

| Tool | Description | |---|---| | get_entities | Fetch entities by ID list (up to 200) via GET /v2/entities | | search_entities | Search entities by type/ID with optional name filter via POST /v2/search | | fetch_children | Fetch child entities of a parent, auto-selects filter strategy by type | | fetch_nearby_entities | Fetch entities within a radius of an entity or lat/lon | | get_entity_type | Resolve the type of a single entity | | get_suggested_airports | Get suggested airports for a city (deprecated endpoint, limited coverage) | | fetch_children_parallel | fetch_children for multiple parents in parallel | | fetch_nearby_entities_parallel | fetch_nearby_entities for multiple locations in parallel | | search_entities_parallel | search_entities for multiple queries in parallel |

Filter strategy by entity type

| Entity type | Filter used | |---|---| | Hotel, Airport, CarHireOffice | relations.geopolitical_parents:containsAny | | TouristAttraction, MetroStation, District, City | hierarchy:isChildOf |

---

Build and deploy

Prerequisites

• Docker Desktop installed and running
• Claude Code

1. Build the image

cd /path/to/this/project
docker build -t mcp-tellus-search .

docker build executes all RUN instructions in the Dockerfile (installs dependencies, copies source). The resulting image is stored in your local Docker registry.

docker run is what actually starts the container and triggers CMD ["python", "src/server.py"].

2. Configure Claude Code

Project-level (only active when Claude Code is opened in this directory):

.mcp.json is already configured: ``json { "mcpServers": { "mcp-tellus-search": { "command": "docker", "args": ["run", "--rm", "-i", "mcp-tellus-search"] } } } ``

Global (active in any directory):

Add to ~/.claude.json under mcpServers: ``json "mcp-tellus-search": { "type": "stdio", "command": "docker", "args": ["run", "--rm", "-i", "mcp-tellus-search"] } ``

3. Restart Claude Code

Run /mcp to verify the server shows as connected.

---

How Claude Code finds .mcp.json

Claude Code scans upward from the current working directory for .mcp.json, the same way git looks for .git. It also loads global MCP servers from ~/.claude.json. Project-level config takes precedence over global config for servers with the same name.

---

Distributing the image

To share this server with others without requiring them to build from source:

# Push to Docker Hub
docker push your-username/mcp-tellus-search

# Others only need .mcp.json pointing to the image name
# Docker pulls it automatically on first run

This is the key advantage of Docker packaging: the recipient needs no Python, no pip install — just Docker and the .mcp.json config file.

---

Tellus API reference

• Base URL: https://gateway.skyscanner.net/travel-api/v2
• Docs: Travel API v2 User Guide
• Use geometry_centroid instead of geometry (per API guidelines)
• Parallel fetch functions use ThreadPoolExecutor with MAX_WORKERS=10 (~8x speedup)
• Do not use requests.Session() in parallel code — use plain requests.post() which is thread-safe