kiliczsh/yolcu360-mcp-server

Yolcu360 MCP Server

MCP (Model Context Protocol) server for the Yolcu360 car rental API. Enables AI assistants to search, book, and manage rental car reservations.

Features

• 15 Tools: Location search, car search, order management, payments, Findeks credit verification
• 5 Resources: Car classes, fuel types, transmission types, delivery types, suppliers
• 2 Prompts: car-search-workflow, booking-workflow
• 2 Transports: HTTP (Streamable HTTP) and stdio (for Claude Desktop)

Prerequisites

• Bun runtime installed
• Yolcu360 API credentials (key and secret)

Installation

# Install dependencies
bun install

# Configure environment
cp .env.example .env
# Edit .env with your Yolcu360 API credentials

Configuration

Edit .env file:

YOLCU360_API_KEY=your-api-key
YOLCU360_API_SECRET=your-api-secret
YOLCU360_API_URL=https://staging.api.pro.yolcu360.com/api/v1
TRANSPORT=http
PORT=3000

Running the Server

HTTP Mode (default)

bun start
# or
bun run start:http

Server endpoints:

• Health: http://localhost:3000/health
• MCP: http://localhost:3000/mcp

stdio Mode

bun run start:stdio

Available Tools

Location Tools

• search-locations - Search for pickup/dropoff locations
• get-location-details - Get location coordinates and details

Search Tools

• search-cars - Search available rental cars by coordinates and dates
• get-car-extras - Get available extras (insurance, GPS, child seat, etc.)

Order Tools

• create-order - Create a new rental order
• get-order - Get order details
• check-cancel-eligibility - Check if order can be cancelled
• cancel-order - Cancel an order

Payment Tools

• process-payment - Process payment (credit card or agency credit)
• get-installment-info - Get installment options for a card

Findeks Tools (Credit Verification)

• check-findeks-eligibility - Check existing credit status
• get-findeks-phones - Get registered phone numbers
• generate-findeks-report - Start credit report generation
• confirm-findeks-pin - Confirm SMS PIN
• renew-findeks-pin - Request new PIN

Health Tool

• check-health - Check API service status

Available Resources

Available Prompts

Claude Desktop Integration

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json on Linux/Mac or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "yolcu360": {
      "command": "bun",
      "args": ["run", "/path/to/yolcu360-mcp-server/src/index.ts"],
      "env": {
        "YOLCU360_API_KEY": "your-api-key",
        "YOLCU360_API_SECRET": "your-api-secret",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Development

# Run with hot reload
bun dev

# Type check
bun run typecheck

# Run tests
bun test

Project Structure

src/
├── index.ts              # Entry point
├── server.ts             # MCP server setup
├── config.ts             # Environment config
├── auth/
│   └── manager.ts        # Token management
├── tools/
│   ├── index.ts          # Tool aggregator
│   ├── health.tools.ts
│   ├── location.tools.ts
│   ├── search.tools.ts
│   ├── order.tools.ts
│   ├── payment.tools.ts
│   └── findeks.tools.ts
├── resources/
│   ├── index.ts
│   └── helper-data.ts
├── prompts/
│   ├── index.ts
│   └── workflows.ts
├── transports/
│   ├── http.ts
│   └── stdio.ts
└── utils/
    └── error-handler.ts

License

MIT