mcp-emtrafesa

MCP Emtrafesa exposes a server that lets clients access Emtrafesa bus information in Peru through standardized MCP tools. You can query terminals, schedules, and purchased tickets, and download tickets as PDFs. The available tools include: get-terminals to fetch all bus terminals in Peru, get-arrival-terminal to retrieve destination terminals from a given origin, get-departure-schedules to obtain schedules between two terminals (with an optional date), get-latest-purchased-tickets to search for tickets by DNI and email, get-ticket-pdf to download a ticket as a PDF, and get-frequently-asked-questions to fetch common questions about the service. These tools are invoked via the MCP client by calling client.callTool with the tool name and, when required, parameter objects such as departureTerminalId, arrivalTerminalId, date, DNI, email, or ticketCode.

To use the server, include it in your MCP client configuration as shown in the Quick Start. You can run the server locally using Bun and the provided index.ts entry point, then interact with the tools from your client by calling the respective tool names and passing the required parameters. The server is designed to work with MCP-compatible clients and supports common MCP workflows like retrieving schedules, listing terminals, and obtaining tickets in PDF form for printing or sharing.

Prerequisites:

• Node.js v18+ or Bun runtime
• Access to Git and a network connection to install dependencies

Installation steps:

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

2. Install dependencies (choose Bun or Node-based workflow)

   • Using Bun (recommended by the project): bun install

   • If you prefer npm/yarn, first install dependencies (if package.json supports it): npm install

3. Run the MCP server locally

   • With Bun: bun run index.ts

   • If using npm scripts, ensure an appropriate start script is defined, then run: npm run start

4. Verify the server is running by testing a tool call via your MCP client, e.g., call get-terminals.

Note: The README's Quick Start demonstrates using npx for clients: you can also use the suggested approach in your MCP client config as shown below.

Tips and considerations:

• The recommended client integration uses npx to fetch the latest mcp-emtrafesa package version at runtime. This ensures you are always using the most up-to-date MCP tool definitions.
• If debugging, you can use the MCP Inspector tool as described in the README: bunx @modelcontextprotocol/inspector bun index.ts
• Ensure your MCP client is compatible with the MCP specification and passes the required parameters for each tool. For example, get-departure-schedules requires departureTerminalId and arrivalTerminalId, with an optional date in DD/MM/YYYY format.
• The server supports standard MCP tooling patterns; when deploying in production, consider containerization (e.g., Docker) or a PM2 process manager to maintain uptime and logging.
• The project lists Bun as a runtime option; you can switch to Node if Bun is not available in your environment, but ensure the runtime matches what the project supports.