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

📋 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

Parameter	Type	Required	Default	Description
from	string	Yes	-	Departure station name (e.g., "Ankara")
to	string	Yes	-	Arrival station name (e.g., "Eskişehir")
date	string	Yes	-	Travel date in YYYY-MM-DD format (e.g., "2025-12-25")
passengerCount	number	No	1	Number of passengers
includeWheelchairSeats	boolean	No	true	Include wheelchair-accessible seats in results

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