# gbfs-mcp 🚲

> **General Bikeshare Feed Specification (GBFS v3.0 / v2.3)** Model Context Protocol (MCP) server & interactive CLI.

Connect AI assistants (Antigravity, Claude Desktop, Cursor, Claude Code) and developers to real-time bikeshare and micromobility availability worldwide across **1,000+ public systems** (Citi Bike, Bay Wheels, Vélib', Santander Cycles, Biki, Lime, and more).

---

## 🌟 Features

- **🌐 1,000+ Worldwide Systems:** Built-in integration with MobilityData’s official `systems.csv` catalog.
- **⚡ Dynamic Auto-Discovery:** Seamlessly parses `gbfs.json` for both GBFS v3.0 (flat feed manifests) and GBFS v2.x (multi-language feed manifests).
- **📍 Geographic Proximity Sorting:** Rank stations and free-floating e-bikes/scooters by distance (`lat`, `lon`, `radius_meters`).
- **🔋 Fleet & Battery Telemetry:** Real-time visibility into vehicle types, electric vs. mechanical bikes, battery ranges, and dock availability.
- **🤖 Built-in Agent Skill (`SKILL.md`):** Complete agent guide included for querying and reasoning about shared micromobility feeds.

---

## 🛠️ MCP Tools

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `gbfs_list_systems` | `query?`, `limit?` | Search 1,000+ public bikeshare systems by city, country, or system ID. |
| `gbfs_get_system` | `system_id_or_url` | Resolves `gbfs.json` manifest, operator info, and available endpoints. |
| `gbfs_get_stations` | `system_id_or_url`, `latitude?`, `longitude?`, `radius_meters?`, `limit?` | Fetches live station capacity, available bikes, e-bikes, and empty docks with proximity ranking. |
| `gbfs_get_free_bikes` | `system_id_or_url`, `latitude?`, `longitude?`, `radius_meters?`, `limit?` | Fetches dockless/floating bikes and scooters with battery range. |
| `gbfs_get_alerts` | `system_id_or_url` | Active operational notices, weather closures, or maintenance. |
| `gbfs_get_vehicle_types` | `system_id_or_url` | Vehicle specifications (form factors, propulsion, battery range). |

---

## 🚀 Quick Start (CLI)

```bash
cd E:\development\gbfs-mcp
npm install
npm run build

# Search systems
node dist/index.js systems Minneapolis

# Get live station availability
node dist/index.js stations bay_wheels --limit 10
```

---

## ⚙️ MCP Configuration

Add to your `mcp_config.json`:

```json
{
  "mcpServers": {
    "gbfs-mcp": {
      "command": "node",
      "args": ["E:/development/gbfs-mcp/dist/index.js", "serve"]
    }
  }
}
```

---

## 📄 License

MIT © Amin