YHT Bilet MCP Server

A Model Context Protocol (MCP) server for searching Turkish train (YHT/High-Speed Train) tickets via TCDD API.

Built with MCP TypeScript SDK

✨ Features

• 🚄 Real-time ticket availability from TCDD API

• 🗺️ Station name to ID mapping - automatic station resolution

• 📅 Smart date formatting - automatically formats dates for API (1 day prior at 21:00)

• 👥 Passenger count support - search for multiple passengers

• ♿ Wheelchair accessibility filter - option to include/exclude wheelchair-accessible seats

• ✅ Schema validation with Zod

• 🎯 Future train filtering - only shows trains that haven't departed yet

• 📦 Object-oriented architecture - clean, maintainable, and testable code

Related MCP server: Czech Railways (České dráhy) MCP Server

📋 Table of Contents

• Quick Start

• Installation

• Usage

• License

🚀 Quick Start

# 1. Clone the repository
git clone https://github.com/yourusername/yht-bilet-mcp.git
cd yht-bilet-mcp

# 2. Install dependencies
npm install

# 3. Create environment file
cp .env.example .env

# 4. Add your TCDD authorization token to .env
# (See "Getting Authorization Token" section below)

# 5. Build the project
npm run build

# 6. Add to Claude Desktop config (see Configuration section)

📦 Installation

Prerequisites

• Node.js 18+

• npm or yarn

• Claude Desktop or any MCP-compatible client

Steps

1. Install Dependencies

npm install

2. Set Up Environment Variables

Copy the example environment file:

cp .env.example .env

3. Get Your Authorization Token

1. Visit TCDD E-Ticket Website

2. Open your browser's Developer Tools (F12)

3. Go to the Network tab

4. Perform a ticket search

5. Find the train-availability request

6. Copy the Authorization header value from Request Headers

7. Paste it into your .env file:

AUTH_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU...

Note: Authorization tokens expire after some time. If you get authentication errors, get a fresh token.

4. Build the Project

npm run build

🎮 Usage

Adding to Claude Desktop

Add the server to your MCP client configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "yht-bilet": {
      "command": "node",
      "args": [
        "/absolute/path/to/yht-bilet-mcp/build/index.js"
      ]
    }
  }
}

Important: Use absolute paths, not relative paths!

Available Tools

The server provides one tool: search_train_ticket

Parameters

Example Usage

In Claude Desktop, you can ask:

Are there any train tickets from Ankara to Eskişehir on December 25, 2025 for 2 passengers?

MCP client will translate this to:

{
  "from": "Ankara",
  "to": "Eskişehir",
  "date": "2025-12-25",
  "passengerCount": 2,
  "includeWheelchairSeats": true
}

To exclude wheelchair seats:

Find train tickets from Ankara to Eskişehir on December 25, 2025, but don't show wheelchair seats.

Response Format

The server returns a formatted text response with:

• ✅/✗ Success/failure indicator

• 🚂 Train commercial name

• ⏰ Departure and arrival times

• 💰 Minimum price

• 📍 Available cabin classes with seat counts

Example Response:

✓ Ankara - Eskişehir arası 27.12.2025 tarihi için 3 adet tren sefer bulundu.

🚂 YHT ESKİŞEHİR - ANKARA (11:30 - 12:54):
   Minimum Fiyat: 390 TL
   
   📍 Müsait Kabinler:
      • BUSİNESS: 39 koltuk
      • EKONOMİ: 86 koltuk
      • TEKERLEKLİ SANDALYE: 2 koltuk
...

📝 License

MIT License - see LICENSE file for details

Made with ❤️ for the Turkish rail community

Need help? Open an issue