Emtrafesa

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

CI codecov NPM Version TypeScript Bun MCP License: MIT

• 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]