Skip to main content
Glama

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

lyon_resolve_place

Resolve an address, stop, or personal place

lyon_next_departures

Get TCL departures with theoretical GTFS fallback

lyon_mobility_status

Get transit alerts, accessibility incidents, traffic, and road events where supported

lyon_trip_options

Compare travel modes, including TCL, Vélo'v, car, walking, and park-and-ride

lyon_parking_options

Find public parking and park-and-ride options

lyon_accessibility_check

Check available accessibility evidence

lyon_nearby_facilities

Find facilities near a place

lyon_environment_brief

Get supported environmental indicators; live sources are not configured

lyon_waste_dropoff

Classify waste and find collection facilities

lyon_personal_briefing

Build a briefing from a local profile

Ten MCP tools use application services, local SQLite data, and embedded or live providers. GTFS fallback stays theoretical.

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 stays unknown. 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 delete removes 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

amd64, arm64

linux_<architecture>.tar.gz

macOS

amd64, arm64

darwin_<architecture>.tar.gz

Windows

amd64

windows_amd64.zip

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

Confirm 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_place

Setup 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

$XDG_CONFIG_HOME/grand-lyon-mcp or ~/.config/grand-lyon-mcp

$XDG_DATA_HOME/grand-lyon-mcp or ~/.local/share/grand-lyon-mcp

macOS

~/Library/Application Support/grand-lyon-mcp

Same as configuration

Windows

%APPDATA%\grand-lyon-mcp

%LOCALAPPDATA%\grand-lyon-mcp

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

GRAND_LYON_MCP_CONFIG_DIR

No

Platform configuration directory

YAML and secrets.env location

GRAND_LYON_MCP_DATA_DIR

No

Platform data directory

Downloads and default database directory

GRAND_LYON_MCP_DB_PATH

No

grand_lyon_mcp.db in the data directory

SQLite path

GRAND_LYON_MCP_OFFLINE

No

false; noninteractive setup selects offline

Use fixtures and block HTTP

DATAGRANDLYON_USERNAME, DATAGRANDLYON_PASSWORD

Live mode only

None

DataGrandLyon credentials

GRAND_LYON_MCP_FIXTURES_DIR

No

None; fixtures are embedded

Alternate offline fixture tree

GRAND_LYON_MCP_VERIFY_TLS

No

true

Verify upstream TLS certificates

TRANSITOUS_ENABLED

No

false

Enable optional journey planning

TRANSITOUS_BASE_URL

No

https://api.transitous.org/api/

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-config

The 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

Tool reference

Arguments, result envelopes, filters, and limits

MCP clients

Generated configuration and live credentials

Operations

Configuration, backup, source discovery, GTFS imports, snapshots, and troubleshooting

Data sources

Provider coverage, endpoints, and freshness

Architecture

Package boundaries, lifecycle, storage, and time handling

Testing · Contributing

Local evidence, quality checks, and contribution rules

Migration from Python

Upgrade while keeping configuration and SQLite data

Changelog · Releases

Version history and release archives

Security policy · Attributions

Vulnerability reporting and source-specific licensing

Development and verification

From the source checkout:

make quality

The 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-directory

Status

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 static reports UNSUPPORTED; 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 tools
lyon_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

    B3.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    All tools follow a consistent 'lyon_' prefix and snake_case, with a mix of verb_noun and noun phrases but still predictable and readable.

    Tool Count5/5

    10 tools is well-scoped for a city services MCP, covering mobility, environment, and waste without being excessive or too few.

    Completeness5/5

    The tool set covers core city life domains: transport (departures, trips, parking, status), accessibility, environment, waste, and personal briefing. No obvious gaps.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers