Skip to main content
Glama

BinaSmart MCP server

MCP Registry License: MIT

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.

Related MCP server: Navitia MCP Server

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

Standalone (tool definitions only)

node mcp-server/stdio.mjs starts the same tools over stdio without the BinaSmart database or .env, so MCP directories such as Glama can build it in their own container and read the tool definitions. Calls that need live data return an error pointing to https://bina.et/mcp.

Tests

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

The tests use reserved test phone numbers only.

Licence

MIT. See LICENSE. © 2026 BinaSmart (Ibrahim Kedir).

Available Tools

27 tools
cancel_rideCancel a rideA
DestructiveIdempotent
Inspect

Cancels a BinaSmart ride that has not started yet. A cancellation cannot be undone. Needs the ride id and the rider phone used to book.

Inputs: ride_id (required), rider_phone (required). Returns: note, test, tier, driver, +10 more

find_pool_groupsFind BinaPool cars filling near a pointA
Read-only
Inspect

Cars currently filling within about 2.5 km of a point in Addis Ababa: destination, seats left, seat price, women-only flag, and a share url (https://bina.et/pool/) the rider can open to join. Driver-opened cars at stations are listed first. Requires lat/lng.

Inputs: lat (required), lng (required). Returns: note, count, groups, start_one_url

get_employerA company and its vacanciesA
Read-only
Inspect

A company listed on BinaSmart: what it does, its address and location when we hold them, and every vacancy it has posted. By employer slug from list_jobs or get_job.

Inputs: slug (required). Returns: note, employer, vacancies, source_url

get_ethiopia_guideDigital Ethiopia guideA
Read-only
Inspect

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, Labor ID and LMIS registration and the COC occupational competency certificate (Overseas Employment Proclamation 1389/2025), 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.

Inputs: slug. Returns: note, slug, text, title, +3 more

get_hospital_departmentsHospital departments and slotsA
Read-only
Inspect

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).

Inputs: slug (required), date. Returns: date, demo, book_url, hospital, +3 more

get_hotel_roomsHotel rooms and pricesA
Read-only
Inspect

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

Inputs: slug (required). Returns: demo, hotel, rooms, book_url, +2 more

get_jobOne vacancy in fullA
Read-only
Inspect

The full advert for a single vacancy on BinaSmart, by its slug from list_jobs: the duties and requirements as the employer wrote them, how to apply, and the company behind it with its address when we hold one.

Inputs: slug (required). Returns: job, note, source_url

get_news_articleOne news article in fullA
Read-only
Inspect

The full text of a single BinaSmart news article by its slug from list_news.

Inputs: slug (required). Returns: article, source_url

get_ride_statusRide statusA
Read-only
Inspect

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.

Inputs: ride_id (required), rider_phone (required). Returns: note, test, tier, driver, +10 more

get_tenderOne tender in fullA
Read-only
Inspect

The full text of a single tender notice on BinaSmart, by its slug from list_tenders: requirements, bid bond, where and when to submit, and the link to the original notice.

Inputs: slug (required). Returns: note, tender, source_url

list_eventsUpcoming eventsA
Read-only
Inspect

Upcoming films, concerts, theatre and events on BinaSmart in Addis Ababa with venue, hall, start time, prices per tier and seats left. Seats are chosen and paid at the url returned (Chapa or at the counter); the ticket is a QR code.

Inputs: no named parameters. Returns: count, events, book_hint, source_url

list_filmsAmharic films to watch onlineA
Read-only
Inspect

Licensed Amharic (Ethiopian) films that can be watched online on BinaSmart Watch (bina.et/watch): title in Amharic and English, year, genre, whether it is free or rented for 48 hours (ETB), and the watch url. Free titles are public YouTube releases played through the YouTube player; rentals need Chapa. Optional search by title or genre.

Inputs: limit, query. Returns: count, films, source_url, watch_hint

list_job_fieldsFields of work hiring nowA
Read-only
Inspect

The fields of work with open vacancies on BinaSmart right now and how many are in each, plus the cities hiring most — useful before calling list_jobs with a field or city filter.

Inputs: no named parameters. Returns: cities, fields, source_url

list_jobsJob vacancies in EthiopiaA
Read-only
Inspect

Open job vacancies in Ethiopia listed on BinaSmart (bina.et/jobs): the job title, the company posting it, the city, the deadline and days left, salary and requirements where the advert states them. Thousands of vacancies from Ethiopian job boards and employers, refreshed every morning. Search by keyword in English or Amharic, and filter by field of work (banking, accounting, engineering, it, health, education, sales, ngo, logistics, admin, hospitality, construction, agriculture, legal, security, media) or by city. Open vacancies only unless include_closed is set. Where the assistant shows MCP Apps, the result also appears as job cards with an apply link for each vacancy.

Inputs: city, field, limit, query, +1 more. Returns: jobs, note, count, source_url

list_newsBinaSmart Amharic newsA
Read-only
Inspect

Recent articles from BinaSmart news (bina.et/news), mostly in Amharic: technology, business, law, real estate, construction and employment in Ethiopia. Returns the headline, a short excerpt and the url — call get_news_article for the full text.

Inputs: limit, query, category. Returns: count, articles, source_url

list_overseas_agenciesLicensed Ethiopian overseas employment agenciesA
Read-only
Inspect

Ethiopian agencies that send domestic workers to GCC countries, approved on BinaSmart/GCC Domestic: name, licence, whether it is in the Ministry of Labor and Skills register, and for each country its GCC partner office (the office families contact). Filter by country: UAE, KSA, Qatar, Kuwait, Bahrain, Oman. Recruitment is through LMIS only (Proclamation 1389/2025).

Inputs: country. Returns: count, updated, agencies, source_url

list_pool_corridorsBinaPool corridors and seat pricesA
Read-only
Inspect

BinaPool (ጋራ ጉዞ) is BinaSmart's shared commute in Addis Ababa: up to four riders share one Comfort car and pay per seat. Lists the corridors open right now (Megenagna → Bole, CMC → Bole, Megenagna → Kazanchis, Piassa → Kazanchis, Mexico → Kazanchis; inbound until 13:00 Addis time, outbound after) with their stops, the live seat-price ladder (1–4 riders) and cars currently filling. Riders join at https://bina.et/ride?pool=1.

Inputs: lat, lng. Returns: note, peak, join_url, corridors, +1 more

list_tender_categoriesTender categories open nowA
Read-only
Inspect

The categories of tender open on BinaSmart right now and how many are in each — useful before calling list_tenders with a category filter.

Inputs: no named parameters. Returns: categories, open_total, source_url

list_tendersOpen tenders in EthiopiaA
Read-only
Inspect

Public tender and procurement notices in Ethiopia listed on BinaSmart (bina.et/tenders): the issuing organisation, what is wanted, the deadline and days left, budget when stated, and a link to the original notice. Banks, government bodies, NGOs and World Bank–financed projects. Open tenders only unless include_closed is set. Search by keyword (English or Amharic) and filter by category such as Supply, Construction, Consultancy, Services, Transport.

Inputs: limit, query, newest, category, +1 more. Returns: note, count, tenders, source_url

quote_rideQuote a BinaSmart rideA
Read-only
Inspect

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). request_ride books at the fare this returns. Also returns book_url: a one-tap bina.et link with this route and fare for the user to confirm.

Inputs: pickup (required), dropoff (required). Returns: note, pickup, quotes, dropoff, +7 more

request_rideBook a BinaSmart rideA
Idempotent
Inspect

Books a ride in Addis Ababa at the fixed fare from quote_ride. It sends a real driver, so it takes the pickup, drop-off, tier, fare and the rider's Ethiopian phone number as the user confirmed them. 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.

Inputs: tier (required), pickup (required), dropoff (required), rider_name (required), +4 more. Returns: note, test, tier, driver, +14 more

search_carsCars for sale in Addis AbabaA
Read-only
Inspect

Live new and used cars on bina.et/cars from Addis Ababa dealers' and car markets' own websites, checked every week: make, model, year, price, mileage, fuel, gearbox, the dealer with its own phone and WhatsApp, and a bina.et link with every photo. Use for "used Toyota", "SUV under 10 million birr", "electric car price", "BYD". Not for taxi rides. Source: the BinaSmart car listings at https://bina.et/cars.

Inputs: body, fuel, make, limit, +5 more. Returns: note, count, results, source_url

search_healthHospitals, clinics, dentists and doctors in Addis AbabaA
Read-only
Inspect

Find hospitals, clinics, dentists, laboratories, health centres and doctors in Addis Ababa from BinaSmart Health (bina.et/health, 250+ places from the city map plus services and doctors the facilities confirmed; doctors' licences are checked by the BinaSmart team). Filter by kind, sub-city, a place to be near (nearest first) and a specialty (children, gynecology, eye, heart, bone, fertility, skin, mental health, blood test). Returns each place's bina.et/health page, landline, sub-city, distance, and its services and doctors when known. Not medical advice; emergencies: 907.

Inputs: area, kind, near, limit, +1 more. Returns: note, count, results, source_url

search_hotelsHotels and guest houses in Addis AbabaA
Read-only
Inspect

Hotels, guest houses, pensions, hostels and furnished apartments in Addis Ababa from BinaSmart's directory (1,000+ places from the city map): name, type, sub-city, stars, the hotel's own office phone and website, and its bina.et page. It has no prices or room availability: those come from the hotel, whose phone is included. Not for hospitals or clinics (use search_health) or for shops, restaurants and other buildings (use search_places).

Inputs: area, kind, name, limit, +1 more. Returns: note, count, results, source_url

search_knowledgeSearch BinaSmart knowledgeA
Read-only
Inspect

Semantic search over BinaSmart's knowledge base: every service (BinaRide, BinaPool shared commute, Bina Airport, hotels, cinema, BinaWatch, insurance, flights, property, cars, tenders), the product rules (fixed fares, what is demo, payments), the 25 Digital Ethiopia guides, and practical Addis Ababa knowledge (neighbourhoods, transport hubs, Ethiopian time and calendar, emergency numbers). For questions about BinaSmart, Ethiopian paperwork or getting around Addis. Returns the best-matching passages, each with its source url. Exact fares are not in the passages: they come from quote_ride.

Inputs: query (required), k. Returns: note, query, results

search_placesSearch the BinaSmart directoryA
Read-only
Inspect

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, the phone only for shops that have claimed their listing, 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. For hospitals, clinics, dentists, labs and doctors anywhere in Addis Ababa, use search_health. For food (restaurants, cafes, a dish, "lunch near Megenagna") with no listed shop it returns map_place results from the city map: name, area, distance, coords and ride link, with no phone, hours, prices or menu (see map_note).

Inputs: query (required), limit, category. Returns: note, count, results, source_url

search_propertiesHomes, land and shops for sale or rent in Addis AbabaA
Read-only
Inspect

Live listings on bina.et/property from Addis Ababa real-estate companies' own websites, checked every week: title, price as the company wrote it (some per m² or in USD), bedrooms, size, area, the listing company with its own phone and WhatsApp, the date the company last updated it, and a bina.et link with every photo. Use for "apartment for rent in Bole", "3 bedroom for sale", "ቤት ኪራይ". Every listing and price is as the company published it.

Inputs: area, beds, type, limit, +3 more. Returns: note, count, results, source_url

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 27 tools

    Disambiguation4/5

    Most tools target clearly distinct resources or actions, and descriptions explicitly cross-reference alternatives. However, several search tools (search_places/search_hotels/search_health), BinaPool tools (list_pool_corridors/find_pool_groups), and knowledge tools (search_knowledge/get_ethiopia_guide) have adjacent purposes that rely heavily on descriptions to separate.

    Naming Consistency5/5

    All tools use snake_case with a consistent verb_noun pattern (list_*, get_*, search_*, quote_ride, request_ride, cancel_ride, find_pool_groups). Minor verb variety is domain-appropriate and does not break the predictable naming convention.

    Tool Count4/5

    27 tools for a multi-vertical super-app covering rides, news, tenders, jobs, property, cars, hotels, health, events, films, guides, and knowledge. Each vertical has a small focused set, but the overall count is on the high side.

    Completeness4/5

    Ride lifecycle is complete, and discovery/detail pairs exist for jobs, tenders, hotels, health, and news. Minor gaps remain for standalone detail tools for events, films, properties, and cars, though search results and external links let agents work around them.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables programmatic WhatsApp automation through MCP, including sending messages, managing chats and contacts, searching conversation history, and exchanging media files.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-aware agents to initiate M-Pesa B2C/B2B payouts, query transaction status, validate phone numbers, and reconcile M-Pesa statements against ledger CSVs to surface discrepancies, plus structured lookups for county public data and KRA tax helpers. It runs in sandbox mode by default, uses idempotency keys for safe retries, and stays read-only for reconciliation and lookups.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables browsing Ethio-Viral's live catalog and placing orders for gift cards, subscriptions, and SMM services from any MCP-capable client using a single API key.
      21
      35 npm
      MIT