BinaSmart

Official9 tools

by akembalo-svg · JavaScript

Ethiopia: Addis rides, jobs, tenders, hotels, health, homes, cars, news and government guides

MCP Server: et.bina/binasmart

This MCP server provides fixed-price ride quote and booking functionality in Addis Ababa. It also supports searching a BinaSmart directory and consulting Ethiopia guides. The server is described as having 9 tools available for interacting with ride and directory/guide information.

🛠️ Key Features

Quote and book fixed-price rides in Addis Ababa
Search the BinaSmart directory
Access Ethiopia guides

🚀 Use Cases

Get ride quotes and place bookings for fixed-price transportation in Addis Ababa
Find entries in the BinaSmart directory
Reference Ethiopia guides during travel planning

⚡ Developer Benefits

Tool-based MCP integration (9 tools)
Consolidates ride and directory/guide search under one server for Addis Ababa and Ethiopia-related content

Topics

addis-ababaamharicethiopiajobsmcpmcp-servermodel-context-protocolride-hailing

Captured live from the server via tools/list.

quote_ride

Fixed upfront price for a ride inside Addis Ababa, Ethiopia — no surge, cash or telebirr/Chapa. Returns distance, ETA and the fare for every vehicle tier (moto, bajaj, economy, comfort, XL). Call this before request_ride and read the fare to the user.

Parameters2

pickup	string	required	Pickup: a place name in Addis Ababa (e.g. "Edna Mall", "Bole Airport", "Piassa") or "lat,lng" like "9.0108,38.7578".
dropoff	string	required	Drop-off: a place name in Addis Ababa (e.g. "Edna Mall", "Bole Airport", "Piassa") or "lat,lng" like "9.0108,38.7578".

Raw schema

{
  "type": "object",
  "properties": {
    "pickup": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120,
      "description": "Pickup: a place name in Addis Ababa (e.g. \"Edna Mall\", \"Bole Airport\", \"Piassa\") or \"lat,lng\" like \"9.0108,38.7578\"."
    },
    "dropoff": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120,
      "description": "Drop-off: a place name in Addis Ababa (e.g. \"Edna Mall\", \"Bole Airport\", \"Piassa\") or \"lat,lng\" like \"9.0108,38.7578\"."
    }
  },
  "required": [
    "pickup",
    "dropoff"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

request_ride

Books a ride in Addis Ababa at the fixed fare from quote_ride. ALWAYS confirm pickup, drop-off, tier, fare and the rider's Ethiopian phone number with the user before calling. A dispatcher assigns a driver; the rider is contacted on the phone given. Returns the ride id and a live tracking link. To book for someone else (e.g. a relative in Addis while you are abroad), pass passenger_name and passenger_phone; rider_name/rider_phone are then the booker and may be a foreign number.

Parameters8

tier	string	required	Vehicle tier from quote_ride
pickup	string	required	Pickup: a place name in Addis Ababa (e.g. "Edna Mall", "Bole Airport", "Piassa") or "lat,lng" like "9.0108,38.7578". Prefer the pickup_coords from quote_ride.
dropoff	string	required	Drop-off: a place name in Addis Ababa (e.g. "Edna Mall", "Bole Airport", "Piassa") or "lat,lng" like "9.0108,38.7578". Prefer the dropoff_coords from quote_ride.
rider_name	string	required	Rider's name (or the booker's name when booking for someone else)
rider_phone	string	required	Ethiopian mobile: 09XXXXXXXX or +2519XXXXXXXX (any number if booking for someone else)
payment_method	string	optional	cash (default) or chapa (telebirr/card link)
passenger_name	string	optional	Book for someone else: the passenger's name (the driver calls the passenger)
passenger_phone	string	optional	Book for someone else: the passenger's Ethiopian mobile (09… or +2519…)

Raw schema

{
  "type": "object",
  "properties": {
    "tier": {
      "type": "string",
      "enum": [
        "moto",
        "bajaj",
        "economy",
        "comfort",
        "xl"
      ],
      "description": "Vehicle tier from quote_ride"
    },
    "pickup": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120,
      "description": "Pickup: a place name in Addis Ababa (e.g. \"Edna Mall\", \"Bole Airport\", \"Piassa\") or \"lat,lng\" like \"9.0108,38.7578\". Prefer the pickup_coords from quote_ride."
    },
    "dropoff": {
      "type": "string",
      "minLength": 2,
      "maxLength": 120,
      "description": "Drop-off: a place name in Addis Ababa (e.g. \"Edna Mall\", \"Bole Airport\", \"Piassa\") or \"lat,lng\" like \"9.0108,38.7578\". Prefer the dropoff_coords from quote_ride."
    },
    "rider_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "Rider's name (or the booker's name when booking for someone else)"
    },
    "rider_phone": {
      "type": "string",
      "minLength": 9,
      "maxLength": 20,
      "description": "Ethiopian mobile: 09XXXXXXXX or +2519XXXXXXXX (any number if booking for someone else)"
    },
    "payment_method": {
      "type": "string",
      "enum": [
        "cash",
        "chapa"
      ],
      "description": "cash (default) or chapa (telebirr/card link)"
    },
    "passenger_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "Book for someone else: the passenger's name (the driver calls the passenger)"
    },
    "passenger_phone": {
      "type": "string",
      "minLength": 9,
      "maxLength": 20,
      "description": "Book for someone else: the passenger's Ethiopian mobile (09… or +2519…)"
    }
  },
  "required": [
    "tier",
    "pickup",
    "dropoff",
    "rider_name",
    "rider_phone"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_ride_status

Current status of a BinaSmart ride (dispatching, assigned, arriving, arrived, ontrip, completed, cancelled) with driver name, vehicle and plate once assigned. Needs the ride id and the rider phone used to book.

Parameters2

ride_id	string	required
rider_phone	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "ride_id": {
      "type": "string",
      "minLength": 5,
      "maxLength": 40
    },
    "rider_phone": {
      "type": "string",
      "minLength": 9,
      "maxLength": 20
    }
  },
  "required": [
    "ride_id",
    "rider_phone"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

cancel_ride

Cancels a BinaSmart ride that has not started yet. Confirm with the user first. Needs the ride id and the rider phone used to book.

Parameters2

ride_id	string	required
rider_phone	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "ride_id": {
      "type": "string",
      "minLength": 5,
      "maxLength": 40
    },
    "rider_phone": {
      "type": "string",
      "minLength": 9,
      "maxLength": 20
    }
  },
  "required": [
    "ride_id",
    "rider_phone"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_places

Find buildings, hotels, hospitals and shops in Addis Ababa listed on BinaSmart (bina.et): cafés, restaurants, pharmacies, banks, gyms, salons, clinics, offices. Returns names (English + Amharic), building and unit, phone for shops, coordinates when known (usable as pickup/dropoff for quote_ride), and the bina.et page. Hotels and hospitals are flagged — use get_hotel_rooms / get_hospital_departments for details.

Parameters3

query	string	required	Name or part of a name, English or Amharic
category	string	optional	Shop category filter: cafe \| restaurant \| pharmacy \| retail \| service \| gym \| salon \| clinic \| bank \| office \| other
limit	integer	optional	Max results per kind (default 8)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80,
      "description": "Name or part of a name, English or Amharic"
    },
    "category": {
      "type": "string",
      "description": "Shop category filter: cafe | restaurant | pharmacy | retail | service | gym | salon | clinic | bank | office | other"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "description": "Max results per kind (default 8)"
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_events

Upcoming events on BinaSmart (concerts, cinema, festivals) in Addis Ababa with venue, start time, ticket price from and seats left. Tickets are bought at the link returned.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_hotel_rooms

Room types, nightly prices (ETB), capacity and amenities for a hotel listed on BinaSmart. Use the slug from search_places (is_hotel = true).

Parameters1

slug

string

required

Hotel slug from search_places

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "Hotel slug from search_places"
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_hospital_departments

Departments of a hospital listed on BinaSmart with consultation fee (ETB), doctors, hours, floor/room and appointment slots left for a date. Use the slug from search_places (is_hospital = true).

Parameters2

slug	string	required	Hospital slug from search_places
date	string	optional	YYYY-MM-DD (default today)

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "maxLength": 60,
      "description": "Hospital slug from search_places"
    },
    "date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "YYYY-MM-DD (default today)"
    }
  },
  "required": [
    "slug"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_ethiopia_guide

BinaSmart's bilingual (Amharic + English) step-by-step guides to Ethiopian government and banking services: Fayda ID, telebirr, CBE Birr, e-Passport, eVisa, TIN, business licence, VAT/TOT, customs, driving licence, car import, Yellow Card, bank account, birth/marriage certificate, utility bills, rental agreements, tenant screening. Call with no slug to list guides; call with a slug for the full text. The guides hold the correct official names and links — prefer them over guessing.

Parameters1

slug

string

optional

Guide slug from the list, e.g. tin-registration-ethiopia

Raw schema

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "description": "Guide slug from the list, e.g. tin-registration-ethiopia"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md4 KBView on GitHub

BinaSmart MCP server

The public Model Context Protocol server for BinaSmart (bina.et), Ethiopia's all-in-one platform. Any MCP-capable assistant (Claude, ChatGPT, Gemini and others) can use it to:

Ride in Addis Ababa: quote fixed fares, book a ride (the user confirms first), check its status, cancel it
Find places: buildings, hotels, hospitals and clinics, shops and restaurants, with their bina.et pages
Jobs and tenders: open vacancies by field or city (Amharic or English), employers, open tenders with deadlines. Vacancies show as job cards in assistants that support MCP Apps
Working abroad: licensed Ethiopian overseas employment agencies and their GCC partner offices
Homes and cars: properties for sale or rent, cars for sale
Guides and news: the bilingual Digital Ethiopia guides (Fayda, passport, telebirr, tax, …) and Amharic news
BinaPool: shared commute corridors and groups

Endpoint: https://bina.et/mcp (Streamable HTTP, stateless, no sign-in needed) Registry: et.bina/binasmart on the MCP Registry Docs: GET https://bina.et/mcp · health: https://bina.et/mcp/health

Claude plugin

The plugin/ folder is a Claude plugin: the same MCP server plus five skills that show Claude how to use it for rides, jobs, paperwork, places and tenders. It contains no code, only Markdown skills and one MCP server entry.

Connect

In any client that accepts a remote MCP server, add the URL https://bina.et/mcp. For example, in Claude: Settings → Connectors → Add custom connector.

How it is built

mcp-server/server.mjs: the MCP endpoint (Express + @modelcontextprotocol/sdk)
mcp-server/tools/: one file per tool group (ride, directory, jobs, health, market, content, guides, knowledge, agencies)
mcp-server/widgets/ and mcp-server/lib/widgets.mjs: the job-card page (MCP Apps) served as ui://bina/jobs-v1.html, with the @modelcontextprotocol/ext-apps browser bundle inlined
mcp-server/lib/: phone normalisation, an idempotency key so retries never double-book, a per-caller rate limiter, the ride API client
api/ and hotels/rules.js: the shared usage meter, API-key check and hotel rules from the main BinaSmart app, which this server imports

The server runs next to the private BinaSmart application and reads its data and settings at runtime (database, ride API on localhost, the .env file). No credentials are in this repository. So this code documents exactly what the public endpoint does, but on its own it will not run against BinaSmart data.

Safety

request_ride and cancel_ride are marked as write tools (readOnlyHint: false), so clients ask the user before calling them.
The job-card page only reads the tool result: it opens bina.et links through the host and can reach no other site.
Reviewers can test request_ride with the reserved number 0900000099: it returns a clearly marked test booking and no driver is sent.
Bookings are limited per phone (5 per 10 minutes) and per caller (10 per hour). Retries with the same details within 10 minutes return the same booking instead of a second one.
Only Ethiopian phone numbers are accepted for rides. Phone numbers are masked in logs.
Privacy: bina.et/privacy · Terms: bina.et/terms · Support: bina.et/support

Tests

bash

cd mcp-server && npm install && node --test test/*.test.mjs

The tests use reserved test phone numbers only.

Licence

Install

Tools (9)

quote_riderequest_rideget_ride_statuscancel_ridesearch_placeslist_eventsget_hotel_roomsget_hospital_departments

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://bina.et/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "binasmart": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://bina.et/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

MCP Server: et.bina/binasmart

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

Topics

quote_ride

request_ride

get_ride_status

cancel_ride

search_places

list_events

get_hotel_rooms

get_hospital_departments

get_ethiopia_guide

BinaSmart MCP server

Claude plugin

Connect

How it is built

Safety

Tests

Licence

Install

Remote endpoint

Related servers