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: Claude Desktop (Recommended)

Open your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following entry:

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

Restart Claude Desktop. You'll see an MCP indicator in the bottom-right corner of the chat input when the server is connected.

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

Then point your MCP client to the local server:

{
  "mcpServers": {
    "mcp-emtrafesa": {
      "command": "bun",
      "args": ["/absolute/path/to/mcp-emtrafesa/src/index.ts"]
    }
  }
}

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

Available Tools

| Tool | Description | Parameters | |------|-------------|------------| | get-terminals | Get all bus terminals in Peru | None | | get-arrival-terminals | 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

Once connected, you can ask Claude naturally:

• "What bus terminals does Emtrafesa have?"
• "What schedules are available from Chiclayo to Trujillo on 14/07/2025?"
• "Look up my tickets with DNI 12345678 and email [email protected]"
• "Download the PDF for ticket BP01-123456"

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/
│   │   ├── models/                    # Domain model interfaces
│   │   └── ports/                     # Repository interface (contract)
│   ├── infrastructure/
│   │   ├── http/                      # HTTP repository implementation
│   │   └── mcp/
│   │       └── tools/
│   │           ├── index.ts           # Auto-discovers and registers all tools
│   │           ├── tool.ts            # Tool interface + register() helper
│   │           ├── error.ts           # Shared errorResponse()
│   │           ├── faq/
│   │           │   └── get-frequently-asked-questions/
│   │           │       ├── constants.ts
│   │           │       └── get-frequently-asked-questions.ts
│   │           ├── schedule/
│   │           │   └── get-departure-schedules/
│   │           │       ├── constants.ts
│   │           │       ├── schema.ts
│   │           │       ├── types.ts
│   │           │       └── get-departure-schedules.ts
│   │           ├── terminal/
│   │           │   ├── get-terminals/
│   │           │   │   ├── constants.ts
│   │           │   │   └── get-terminals.ts
│   │           │   └── get-arrival-terminals/
│   │           │       ├── constants.ts
│   │           │       ├── schema.ts
│   │           │       ├── types.ts
│   │           │       └── get-arrival-terminals.ts
│   │           └── ticket/
│   │               ├── get-latest-purchased-tickets/
│   │               │   ├── constants.ts
│   │               │   ├── schema.ts
│   │               │   ├── types.ts
│   │               │   └── get-latest-purchased-tickets.ts
│   │               └── get-ticket-pdf/
│   │                   ├── constants.ts
│   │                   ├── schema.ts
│   │                   ├── types.ts
│   │                   └── get-ticket-pdf.ts
│   ├── 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

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]