Content
<div align="center">
**MCP server for the Valenbisi bike-share system in Valencia**
*Ask your AI assistant to find the nearest station and unlock a bike — right from the chat*
<p>
<img src="https://img.shields.io/github/v/release/galimru/valenbisi-mcp" alt="Latest release">
<img src="https://img.shields.io/badge/MCP-compatible-blueviolet" alt="MCP">
<img src="https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat&logo=go&logoColor=white" alt="Go">
<img src="https://img.shields.io/badge/license-MIT-blue" alt="License">
</p>
</div>
---
Connect your AI assistant to Valenbisi. Ask which stations have bikes, locate a specific bike by number, or unlock a bike — all through natural conversation.
## Quick Start
**1. Install**
```bash
curl -sSL https://galimru.github.io/valenbisi-mcp/install.sh | sh
```
Or download a binary from the [releases page](https://github.com/galimru/valenbisi-mcp/releases).
**2. Connect to Claude Desktop**
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"valenbisi": {
"command": "/usr/local/bin/valenbisi-mcp",
"env": {
"VALENBISI_EMAIL": "you@example.com",
"VALENBISI_PASSWORD": "123456"
}
}
}
}
```
**3. Set `app_token_key`**
Create or edit `~/.config/valenbisi-mcp/config.json`:
```json
{
"unlock_distance": 50,
"app_token_key": "APK_DERIVED_APP_TOKEN_KEY"
}
```
`app_token_key` is required for API-backed tools to work. It is the
Cyclocity app token key derived from the official Android app.
## Tools
| Tool | What it does |
|------|--------------|
| `get_nearest_stations` | Nearest stations to a GPS location, sorted by distance |
| `get_nearest_stations_with_bikes` | Nearest open stations that have bikes available to rent |
| `get_nearest_stations_with_stands` | Nearest open stations that have free docks to return a bike |
| `get_station` | Details for a single station by number |
| `get_bike` | Look up a bike by number — returns its current station and dock |
| `get_bikes_by_station` | List the bikes currently reported at a station |
| `unlock_bike` | Unlock a bike (requires your GPS coordinates; enforces a proximity check at call time) |
| `get_profile` | Your account profile |
| `get_trips` | Your past trips |
| `get_ongoing_trip` | Whether you have a trip in progress right now |
## Configuration
**Environment variables**
| Variable | Required | Description |
|----------|----------|-------------|
| `VALENBISI_EMAIL` | Yes | Your Valenbisi account email |
| `VALENBISI_PASSWORD` | Yes | Your Valenbisi account password |
| `VALENBISI_DEBUG` | No | Set to any non-empty value to log HTTP traffic to stderr |
**Config file**
`~/.config/valenbisi-mcp/config.json` is created on first run with defaults:
```json
{
"unlock_distance": 50,
"app_token_key": ""
}
```
| Field | Required | Description |
|-------|----------|-------------|
| `unlock_distance` | No | Maximum distance from a station to allow `unlock_bike`, in metres. `0` is treated as the default value `50`. |
| `app_token_key` | Yes | Cyclocity app token key used for app-level API authentication. |
`app_token_key` must be configured before API-backed tools can succeed. It
is the Cyclocity app token key derived from the official Android app.
## Notes
- This project is not affiliated with JCDecaux or the Valenbisi service.
- User auth state is cached in `~/.config/valenbisi-mcp/session.json`.
- App-level token state is cached separately in `~/.config/valenbisi-mcp/app_token.json`.
## Contributing
Bug fixes and clear improvements are welcome. Open an issue first for anything non-trivial.
## License
MIT
