mcp-emtrafesa by georgegiosue - MCP Server

MCP Emtrafesa

A Model Context Protocol (MCP) server for accessing Emtrafesa bus transportation services in Peru

English: (You are here)
Español:

MCP Emtrafesa is a Model Context Protocol server that provides AI assistants with seamless access to Peru's Emtrafesa bus transportation system. Query terminals, schedules, tickets, and FAQs through standardized MCP tools.

What can you do with this MCP?

Find bus terminals across Peru
Check schedules between any two cities
Look up your purchased tickets using your DNI and email
Download your ticket as PDF for printing or sharing
Get answers to frequently asked questions

Quick Start

Option 1: Use directly with npx (Recommended)

Add to your MCP client configuration:

{
  "mcpServers": {
    "mcp-emtrafesa": {
      "command": "npx",
      "args": ["mcp-emtrafesa@latest"]
    }
  }
}

Option 2: Clone and run locally

# Clone the repository
git clone https://github.com/georgegiosue/mcp-emtrafesa.git
cd mcp-emtrafesa

# Install dependencies
bun install

# Start the MCP server
bun run index.ts

Tip: Use the MCP Inspector for debugging: bunx @modelcontextprotocol/inspector bun index.ts

Available Tools

Tool	Description	Parameters
`get-terminals`	Get all bus terminals in Peru	None
`get-arrival-terminal`	Get destination terminals for a given origin	`departureTerminalId`
`get-departure-schedules`	Get schedules between two terminals	`departureTerminalId`, `arrivalTerminalId`, `date?`
`get-latest-purchased-tickets`	Search your purchased tickets	`DNI`, `email`
`get-ticket-pdf`	Download your ticket as a PDF file	`ticketCode`
`get-frequently-asked-questions`	Get FAQs about the service	None

Usage Examples

Get all terminals

const terminals = await client.callTool("get-terminals");

Find schedules from Chiclayo to Trujillo

const schedules = await client.callTool("get-departure-schedules", {
  departureTerminalId: "002",
  arrivalTerminalId: "001",
  date: "14/07/2025", // DD/MM/YYYY format
});

Look up your purchased tickets

const tickets = await client.callTool("get-latest-purchased-tickets", {
  DNI: "12345678",
  email: "user@example.com",
});

Download your ticket as PDF

const pdf = await client.callTool("get-ticket-pdf", {
  ticketCode: "BP01-123456",
});
// Returns a base64-encoded PDF that can be saved or displayed

Requirements

Bun v1.2.10+ or Node.js v18+
An MCP-compatible client (Claude Desktop, etc.)

Project Structure

mcp-emtrafesa/
├── src/
│   ├── config/                # API configuration
│   ├── domain/                # Domain layer
│   │   ├── models/            # Domain models
│   │   └── ports/             # Repository interfaces
│   ├── infrastructure/        # Infrastructure layer
│   │   ├── http/              # HTTP repository implementations
│   │   └── mcp/               # MCP server tools
│   ├── shared/                # Shared utilities
│   └── index.ts               # MCP server entry point
├── package.json
└── tsconfig.json

Development

# Format code
bun run format

# Check formatting
bunx biome check

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/new-feature)
Format your code (bun run format)
Commit your changes
Open a Pull Request

georgegiosue/mcp-emtrafesa