MCP Emtrafesa

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

• English: README.md (You are here)
• Español: README.es.md

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: "[email protected]",
});

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/
│   ├── common/         # Shared tools and utilities
│   ├── config/         # API configuration
│   ├── internal/       # Core business logic (services, types)
│   └── lib/            # Helper utilities
├── index.ts            # MCP server entry point
├── package.json
└── tsconfig.json

Development

# Format code
bun run format

# Check formatting
bunx biome check

Contributing

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

License

MIT License - see LICENSE for details.

Acknowledgments

• Emtrafesa - Transportation API provider
• Model Context Protocol - MCP specification
• @tecncr - API endpoint insights
• Bun - Fast JavaScript runtime

Support

• GitHub Issues
• GitHub Discussions
• Email: [email protected]