grand-lyon-mcp
The server provides ten read-only MCP tools for Lyon mobility and local services, run locally over stdio with SQLite and optional live/offline data sources.
Resolve addresses, TCL stops, Vélo'v stations, neighborhoods, or personal places.
Get next TCL departures, with theoretical GTFS fallback when needed.
Check transit alerts, accessibility incidents, traffic, and road events.
Compare travel options across TCL, Vélo'v, park-and-ride, car, and walking.
Find public parking and park-and-ride options, including occupancy when known.
Check accessibility evidence for stops or trips without treating missing data as accessible.
Find nearby facilities such as toilets, fountains, parks, bike pumps, and Vélo'v stations.
Retrieve available environmental indicators for an area, flagging unsupported ones.
Classify waste items and find drop-off or collection facilities.
Build a personal briefing from a local profile; notification delivery is left to the MCP client.
Operate offline with bundled fixtures or live with DataGrandLyon credentials; optional Transitous routing is disabled by default.
Sends geocoding queries and optional location hints to Métropole de Lyon's Photon instance to resolve addresses and places within the Lyon metropolitan area.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@grand-lyon-mcp What are the next TCL departures from Part-Dieu?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Grand Lyon MCP connects an MCP client to Métropole de Lyon open data through a local native binary. Look up departures, compare travel options, find parking and facilities, or build a personal briefing. The executable embeds configuration templates, schemas, SQLite migrations, and offline demonstration fixtures.
Why Grand Lyon MCP?
Use it when an assistant needs structured local mobility information with explicit warnings about incomplete data. The same tools work with live providers or bundled fixtures, and distinguish theoretical GTFS departures, unknown parking occupancy, and missing accessibility evidence.
The server runs locally over stdio and uses SQLite without a separate database service. Live results depend on upstream sources; offline fixtures demonstrate behavior rather than current conditions.
Related MCP server: OpenAI-Compatible MCP Gateway
Privacy and data flows
Accounts: No project account or credentials are needed for offline use. Live mode requires a DataGrandLyon username and password. Transitous routing is optional, disabled by default, and uses no additional credential in this implementation. Your MCP client may have its own account requirements.
Telemetry: The server implements no telemetry or crash reporting. Errors and diagnostics go to stderr; MCP messages use stdout. Your MCP client's data handling is separate.
Data: Configuration and credentials live in user files; SQLite stores imported timetables, indexed places, profiles, briefing snapshots, and Vélo'v history. Offline mode blocks application HTTP requests. Live requests go to DataGrandLyon services; geocoding sends queries and optional location hints to Métropole's Photon instance. Enabled Transitous routing sends origin and destination coordinates and departure time to Transitous. Tool results are returned to your MCP client.
Tools
Tool | Purpose |
| Resolve an address, stop, or personal place |
| Get TCL departures with theoretical GTFS fallback |
| Get transit alerts, accessibility incidents, traffic, and road events where supported |
| Compare travel modes, including TCL, Vélo'v, car, walking, and park-and-ride |
| Find public parking and park-and-ride options |
| Check available accessibility evidence |
| Find facilities near a place |
| Get supported environmental indicators; live sources are not configured |
| Classify waste and find collection facilities |
| Build a briefing from a local profile |
See the tool reference for arguments, defaults, filters, and limitations, and data sources for live provider coverage.
Reading results
Every tool returns an envelope with status, summary, data, sources, warnings, and degraded, plus a schema version, request ID, and generation time.
Statuses are ok, partial, not_found, ambiguous, unavailable, or invalid_request.
MCP marks invalid_request and unavailable results with isError=true while keeping the same domain envelope; partial, ambiguous, and legitimate empty results remain successful. Invalid arguments include an actionable data.error with a stable code, field, and expected constraint.
A successful MCP exchange can contain an unavailable domain result: inspect warnings, source dates, and realtime flags before relying on it.
Input validation. Schemas reject unknown fields and invalid values. A place reference uses exactly one of a query, place ID, coordinate pair, or profile-place name.
Trip eligibility. Only options whose evidence satisfies the walking, deadline, disruption, and accessibility constraints can be recommended. Missing itineraries and unknown walking distances stay visible as ineligible information with a reason.
Data quality. GTFS results are always theoretical. Missing parking occupancy stays
null; zero means full. Missing accessibility evidence staysunknown. Observation time, retrieval time, and age stay separate: missing timestamps remain unknown, and stale or unobserved availability cannot support a recommendation.Local writes. Tools do not change upstream data. Some queries save local briefing snapshots or Vélo'v observations; repeated identical observations are deduplicated, retention is bounded by configuration, and
history deleteremoves scoped personal history. Startup applies pending SQLite migrations.
Administrative tasks such as setup, GTFS imports, and catalogue discovery are CLI commands.
Run grand-lyon-mcp --help for command names and see Operations for procedures.
Get started
Choose a release binary or build from source. Then run the offline example below; it needs no credentials or external data.
Install release 0.2.0
Download your archive and SHA256SUMS from release v0.2.0.
Verify the archive against its checksum before extraction, then put grand-lyon-mcp or grand-lyon-mcp.exe in PATH.
The installed binary needs neither Go nor Python nor a source checkout.
Operating system | Architectures | Archive suffix |
Linux |
|
|
macOS |
|
|
Windows |
|
|
Archive names begin with grand-lyon-mcp_0.2.0_.
For example, from the download directory on Linux amd64:
sha256sum --ignore-missing --check SHA256SUMS &&
tar -xzf grand-lyon-mcp_0.2.0_linux_amd64.tar.gzConfirm that the selected archive is reported OK. On macOS, use shasum -a 256 to calculate its hash; on Windows, use PowerShell Get-FileHash -Algorithm SHA256, and compare with the matching entry in SHA256SUMS.
Build from source
Requirements: Go 1.26 or later, Git, and Make for the commands below.
git clone https://github.com/ThomasCrouzet/mcp-grand-lyon.git
cd mcp-grand-lyon
go mod download
make build
export PATH="$PWD/bin:$PATH"make build sets CGO_ENABLED=0 and writes bin/grand-lyon-mcp.
The shell examples use a POSIX shell; on Windows, invoke the extracted .exe from PowerShell.
Run your first operation
For a disposable demo, run these commands in the same POSIX shell with the binary in PATH.
The exported paths keep the example separate from your normal configuration and database:
demo_dir="$(mktemp -d)"
export GRAND_LYON_MCP_CONFIG_DIR="$demo_dir/config"
export GRAND_LYON_MCP_DATA_DIR="$demo_dir/data"
export GRAND_LYON_MCP_DB_PATH="$demo_dir/data/grand_lyon_mcp.db"
export GRAND_LYON_MCP_OFFLINE=true
grand-lyon-mcp setup --yes --offline
grand-lyon-mcp doctor
grand-lyon-mcp smoke --tool lyon_resolve_placeSetup writes YAML templates, secrets.env, and mcp-client.snippet.json in the configuration directory and migrates SQLite.
doctor should report status: "OK" and offline: true.
The smoke command resolves Part-Dieu with a limit of three; with bundled fixtures and a fresh database, its last two lines are:
lyon_resolve_place partial 2 place candidate(s).
1/1 tools returned an accepted envelope.This result was verified against the embedded fixtures. Its partial status reflects demonstration data, not current conditions.
Continue to MCP setup to use the same operation from a client.
For a regular installation, open a fresh shell without these demo overrides and run grand-lyon-mcp setup --yes --offline again.
Configuration and data
The binary uses native user directories by default:
Platform | Configuration | Data |
Linux |
|
|
macOS |
| Same as configuration |
Windows |
|
|
Run grand-lyon-mcp env --config-dir to print the resolved configuration directory.
Configuration precedence, from highest to lowest, is nonempty process environment, active settings.yaml fields, legacy secrets.env overrides during migration, then built-in defaults.
secrets.env stores only DATAGRANDLYON_USERNAME, DATAGRANDLYON_PASSWORD, and the configuration-directory bootstrap; ordinary settings live in settings.yaml or explicit launch environment variables.
grand-lyon-mcp config explain reports each effective setting with its origin, and grand-lyon-mcp config migrate moves legacy nonsecret overrides into settings.yaml without changing their effective values.
The initial configuration directory selects which secrets.env is read. The parser never evaluates shell syntax, and the binary does not load the repository's .env file.
Setting | Required | Built-in default | Purpose |
| No | Platform configuration directory | YAML and |
| No | Platform data directory | Downloads and default database directory |
| No |
| SQLite path |
| No |
| Use fixtures and block HTTP |
| Live mode only | None | DataGrandLyon credentials |
| No | None; fixtures are embedded | Alternate offline fixture tree |
| No |
| Verify upstream TLS certificates |
| No |
| Enable optional journey planning |
| No |
| Planner base URL; does not expand the HTTP host allowlist |
Effective mode: Embedded fixtures are used only when the offline setting is explicitly true. Live mode stays live when credentials are missing: public geocoding and an enabled journey planner remain available, credential-dependent sources report CREDENTIALS_MISSING, and imported GTFS remains a theoretical local fallback. doctor reports requested mode, effective mode, local installation health, and per-source capabilities; it exits 3 when live mode lacks credentials. Check doctor and config explain after changing modes; a pre-existing installation that relied on the old implicit fixture fallback must set runtime.offline: true explicitly.
For live use, set both credentials in your environment, run grand-lyon-mcp setup --yes --live, and regenerate the MCP configuration.
Setup stores credentials in user secrets.env; on Unix it uses mode 0600. Keep credentials out of client JSON and commits.
On Unix, setup and direct startup create the application data directory with mode 0700 and the SQLite database with 0600; doctor reports unexpected broader permissions and grand-lyon-mcp db secure applies the documented remediation without touching unrelated paths.
Edit the generated profiles.yaml to replace demonstration home/work places and the weekday_morning briefing.
See Operations for timeouts, concurrency, journey weights, and accepted legacy settings that do not affect runtime behavior.
Read Migration from Python before replacing a prior installation or reusing its database.
Connect an MCP client
The only transport is stdio. The client launches grand-lyon-mcp serve --transport stdio as a child process.
No HTTP endpoint or separately running server is needed. Running serve in a terminal waits for protocol messages; it has no interactive prompt.
After setup, print absolute paths and the launch configuration:
grand-lyon-mcp client-configThe generated document uses a top-level mcpServers object and contains paths and the offline flag, without credentials.
Adapt its structure to your client's documented format.
VS Code
With AI features enabled, open a local workspace and create or edit .vscode/mcp.json.
Use the command and env values from client-config in this VS Code configuration format:
{
"servers": {
"grand-lyon": {
"type": "stdio",
"command": "/absolute/path/grand-lyon-mcp",
"args": ["serve", "--transport", "stdio"],
"env": {
"GRAND_LYON_MCP_CONFIG_DIR": "/absolute/config/path",
"GRAND_LYON_MCP_DATA_DIR": "/absolute/data/path",
"GRAND_LYON_MCP_DB_PATH": "/absolute/data/path/grand_lyon_mcp.db",
"GRAND_LYON_MCP_OFFLINE": "true"
}
}
}
}Replace every example path with its generated value; on Windows, JSON paths need escaped backslashes or forward slashes.
Save, run MCP: List Servers, select grand-lyon, and start or restart it. Review the client trust prompt.
Enable the server's tools in the chat tool picker and confirm that discovery lists ten lyon_* tools.
Ask the agent to call lyon_resolve_place on grand-lyon with these arguments:
{"query": "Part-Dieu", "limit": 3}With the fresh offline setup above, inspect the returned envelope for status: "partial", summary: "2 place candidate(s).", candidates named Part-Dieu and Gare Part-Dieu, and the OFFLINE_FIXTURE warning.
degraded is true, provenance identifies Fixtures / offline_demo, and simulated records use realtime=false.
Request IDs and generation/retrieval times vary. This example result was verified through an initialized stdio session using bundled fixtures.
For startup failures, inspect the client's server output for stderr diagnostics. See MCP clients for generated snippets and live credential setup, and VS Code's setup guide for client controls.
Documentation
Guide | Contents |
Arguments, result envelopes, filters, and limits | |
Generated configuration and live credentials | |
Configuration, backup, source discovery, GTFS imports, snapshots, and troubleshooting | |
Provider coverage, endpoints, and freshness | |
Package boundaries, lifecycle, storage, and time handling | |
Local evidence, quality checks, and contribution rules | |
Upgrade while keeping configuration and SQLite data | |
Version history and release archives | |
Vulnerability reporting and source-specific licensing |
Development and verification
From the source checkout:
make qualityThe gate checks formatting, module state, Go diagnostics, race-enabled tests, and known vulnerabilities.
Process tests launch CLI and MCP children outside the checkout and retain repeatable local evidence and protocol transcripts.
make test enforces 85% coverage with documented boundary exclusions; see Testing for the scope and external artifact paths.
Keep reports in local storage; do not upload them to GitHub.
To build the five release archives and SHA256SUMS, choose an output path that does not exist:
make release RELEASE_DIR=/new/external/release-directoryStatus
Version 0.2.0 replaces the Python runtime with a native Go executable while retaining the ten tool names, configuration variables, and SQLite migration history.
Current limitations:
Provider coverage. Live traffic conditions and environmental indicators have no configured feed. Other live sources can be incomplete or unavailable.
Routing. Transitous is optional and disabled by default. TCL duration can be unavailable without a successful planner result.
Offline data. Fixtures have fixed dates and always carry demonstration warnings. They do not describe current availability or conditions.
Local imports. Theoretical fallback needs an imported GTFS timetable. Departure lookup near coordinates or personal places requires an imported stop within 500 metres.
Maintenance.
sync staticreportsUNSUPPORTED; the application installs no scheduler for Vélo'v snapshots.
Report reproducible bugs through GitHub Issues, including the binary version, effective mode, command or tool arguments, and redacted diagnostics. Use the security policy for vulnerabilities.
License and credits
Code uses the MIT license. Copyright (c) 2026 Thomas Crouzet.
Data has source-specific licenses; see Attributions, including the requirement to credit OpenStreetMap-derived data to “© OpenStreetMap contributors”.
Release archives include THIRD_PARTY_NOTICES.txt for bundled software.
This project is independent of Métropole de Lyon, SYTRAL Mobilités, Keolis-TCL, and JCDecaux.
Available Tools
10 toolslyon_accessibility_checkA
Vérifie l'accessibilité (fauteuil, sans marche) d'arrêts ou d'un trajet. L'absence de donnée n'est jamais assimilée à accessible.
Inputs: needs, stops, origin, destination. Returns: object
lyon_environment_briefA
Indicateurs environnementaux disponibles (pollen, qualité de l'air, chaleur) pour une zone. Les indicateurs sans source sont signalés sans bloquer les autres.
Inputs: location (required), at, indicators. Returns: object
lyon_mobility_statusC
État des transports et de la circulation : alertes TCL, accessibilité, trafic, chantiers. Pas pour les prochains passages d'un arrêt précis.
Inputs: areas, lines, include. Returns: object
lyon_nearby_facilitiesC
Équipements urbains à proximité : toilettes, fontaines, parcs, pompes à vélo, stations Vélo'v.
Inputs: location (required), categories (required), open_at, radius_m, +1 more. Returns: object
lyon_next_departuresB
Retourne les prochains passages TCL à un arrêt ou une station. Pour les horaires immédiats uniquement. Pour un trajet complet, utilisez lyon_trip_options.
Inputs: stop (required), at, line, limit, +1 more. Returns: object
lyon_parking_optionsC
Parkings publics et parcs relais près d'une destination, avec places disponibles si connues.
Inputs: destination (required), limit, types, radius_m, +1 more. Returns: object
lyon_personal_briefingC
Briefing personnel selon un profil local (trajet habituel, alertes, Vélo'v). N'envoie aucune notification : le déclenchement et la livraison sont à la charge du client MCP appelant.
Inputs: profile (required), at, compare_with_previous. Returns: object
lyon_resolve_placeA
Résout une adresse, un arrêt TCL, une station Vélo'v, un quartier ou un lieu personnel dans la Métropole de Lyon. Utilisez cet outil avant les autres lorsqu'un lieu est ambigu. Ne calcule pas d'itinéraire.
Inputs: near, limit, query, types. Returns: object
lyon_trip_optionsB
Compare des modes de déplacement (TCL, Vélo'v, P+R, voiture, marche) entre deux lieux. Ne remplace pas lyon_next_departures pour un seul arrêt.
Inputs: origin (required), destination (required), modes, preferences, +2 more. Returns: object
lyon_waste_dropoffC
Classe un objet à jeter (taxonomie déterministe) et propose des déchèteries / points de collecte.
Inputs: item (required), limit, open_at, location, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool has a clearly distinct purpose: place resolution, departures, mobility status, nearby facilities, trip options, parking, accessibility, environment, waste disposal, personal briefing. No overlap or ambiguity.
All tools follow a consistent 'lyon_' prefix and snake_case, with a mix of verb_noun and noun phrases but still predictable and readable.
10 tools is well-scoped for a city services MCP, covering mobility, environment, and waste without being excessive or too few.
The tool set covers core city life domains: transport (departures, trips, parking, status), accessibility, environment, waste, and personal briefing. No obvious gaps.
Maintenance
Related MCP Connectors
An MCP server for Georgian public data, read from the organizations that publish it.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for French (BOAMP) + EU (TED) public procurement data via TenderAPI.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for exploring French public open data via APIs like data.gouv.fr, geo.api.gouv.fr, INSEE Sirene, and Radio France.11MIT
- FlicenseNot gradedqualityDmaintenanceLocal MCP server that exposes fixed tools for GPT, Claude, and Gemini while routing to any OpenAI-compatible chat completions backend with independent configuration per target.1-
- AlicenseNot gradedqualityDmaintenanceMCP server to query French Open Data from data.gouv.frMIT
- AlicenseAqualityCmaintenanceA local stdio MCP server exposing the Bixi Montréal bike-share API as tools, enabling users to list stations in service and view their ride history through MCP clients.2MIT