grand-lyon-mcp

FR | English below

Serveur MCP local qui agrège les services ouverts de la Métropole de Lyon (TCL, Vélo’v, parkings, trafic, équipements, déchets, briefings) derrière 10 outils métier en lecture seule. Se branche sur n’importe quel client MCP en stdio (Claude Desktop, Cursor, agents maison…).

Les identifiants DataGrandLyon ne sont jamais versionnés, loggés ou renvoyés par les outils.

Fonctionnalités

• Prochains passages TCL (temps réel + repli GTFS théorique)
• Alertes / mobilité / accessibilité
• Vélo’v + historique local
• Parkings & P+R
• Trafic & événements routiers
• Équipements (toilettes, fontaines, parcs…)
• Environnement (indicateurs optionnels)
• Classification déchets + déchèteries
• Comparaison d’options de trajet
• Briefings personnels configurables

Architecture

MCP adapter → application services → domain protocols → providers → HTTP / SQLite

Le code métier n’importe pas le SDK MCP (adapters/mcp/ uniquement).

Prérequis

• Python ≥ 3.12
• uv
• Compte DataGrandLyon (optionnel : sans compte → mode offline/fixtures)

Installation

Assistant recommandé

git clone git@github.com:ThomasCrouzet/mcp-grand-lyon.git
cd mcp-grand-lyon
make setup              # TUI interactive (gum si dispo, sinon prompts)
# ou sans interaction :
make setup-offline      # fixtures, aucun compte requis

L’assistant écrit les secrets dans secrets.env (chmod 600), copie les YAML de config, installe les deps, migre SQLite et lance doctor.

Chemin des secrets selon l’OS (résolu par platformdirs) :

• Linux : ~/.config/grand-lyon-mcp/secrets.env
• macOS : ~/Library/Application Support/grand-lyon-mcp/secrets.env
• Windows : %APPDATA%\grand-lyon-mcp\secrets.env

grand-lyon-mcp env affiche le chemin réel résolu sur votre machine. Vous pouvez aussi forcer un répertoire via GRAND_LYON_MCP_CONFIG_DIR.

Manuel

uv sync --all-extras --dev
cp .env.example "$(uv run grand-lyon-mcp env --config-dir)/secrets.env"
# éditer : DATAGRANDLYON_USERNAME / PASSWORD, puis chmod 600
make migrate

Variables : voir .env.example. Le Makefile charge automatiquement secrets.env et un .env local gitignored.

make help               # toutes les cibles
make env                # état config (secrets masqués)
make serve OFFLINE=true LOG_LEVEL=DEBUG
make client-config      # bloc mcpServers JSON (chemins absolus)

Configuration

Les templates de configuration (settings, sources, profiles, waste-taxonomy) sont livrés avec le paquet (grand_lyon_mcp/_data/config/). L'assistant les copie dans votre répertoire de config :

grand-lyon-mcp setup            # copie les YAML + migre (ou : make setup)

Pour les inspecter ou repartir des templates empaquetés manuellement :

python -c "from grand_lyon_mcp.resources import config_dir; print(config_dir())"

Migrations & données

uv run grand-lyon-mcp db migrate
uv run grand-lyon-mcp db info
uv run grand-lyon-mcp doctor
uv run grand-lyon-mcp catalog scan
uv run grand-lyon-mcp catalog validate
uv run grand-lyon-mcp sync gtfs
# offline GTFS :
uv run grand-lyon-mcp sync gtfs --from-file tests/fixtures/gtfs/mini_gtfs.zip
uv run grand-lyon-mcp snapshot velov

Démarrage MCP (stdio)

uv run grand-lyon-mcp serve --transport stdio
# ou
./scripts/run_mcp.sh

stdout est réservé au protocole MCP ; les logs applicatifs vont sur stderr.

Brancher un client MCP

Le serveur parle le protocole MCP en stdio : il fonctionne avec tout client compatible. Récupérez un bloc prêt à coller (chemins absolus) avec :

make client-config      # ou : uv run grand-lyon-mcp client-config

Exemple de configuration Claude Desktop (claude_desktop_config.json) :

{
  "mcpServers": {
    "grand-lyon": {
      "command": "/chemin/absolu/mcp-grand-lyon/scripts/run_mcp.sh",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Le wrapper scripts/run_mcp.sh charge secrets.env hors dépôt et bascule en offline si aucun identifiant n’est présent. Le même bloc convient à Cursor et aux autres clients MCP stdio. Détails et alternatives (env hérité, secrets) : docs/mcp-clients.md.

Outils MCP (10)

Outil	Rôle
lyon_resolve_place	Résolution de lieux (adresse, arrêt, station, lieu personnel)
lyon_next_departures	Prochains passages TCL
lyon_mobility_status	Alertes & trafic
lyon_trip_options	Comparaison de modes
lyon_parking_options	Parkings / P+R
lyon_accessibility_check	Accessibilité
lyon_nearby_facilities	Équipements
lyon_environment_brief	Environnement
lyon_waste_dropoff	Déchets
lyon_personal_briefing	Briefing profil

Aucun outil admin / requête brute DataGrandLyon n’est exposé. Arguments détaillés et exemples d’entrée/sortie : docs/tools.md.

Exemple — lyon_next_departures :

// entrée
{ "stop": { "query": "Bellecour" }, "line": "A", "limit": 3 }
// sortie (extrait de l'enveloppe)
{
  "status": "ok",
  "data": { "departures": [
    { "line_name": "A", "destination": "Vaulx-en-Velin La Soie",
      "expected_at": "2026-07-20T08:05:00+02:00", "realtime": true }
  ] },
  "sources": [ { "provider": "DataGrandLyon", "attribution": "SYTRAL Mobilités", "realtime": true } ]
}

Tests

make quality
# ou
uv run ruff format --check .
uv run ruff check .
uv run mypy src
uv run pytest -m "not live" --cov

Tests live : RUN_LIVE_TESTS=1 + credentials. La suite par défaut tourne sans réseau ni identifiants.

Documentation

Doc	Contenu
docs/architecture.md	Architecture
docs/tools.md	Les 10 outils MCP (arguments, exemples)
docs/mcp-clients.md	Configuration des clients MCP
docs/data-sources.md	Sources & licences
ATTRIBUTIONS.md	Attributions open data & dépendances
docs/operations.md	Exploitation
docs/troubleshooting.md	Dépannage
docs/adr/	Décisions d’architecture

Limites (v0.1)

• Transitous optionnel (feature flag) ; sans routeur, lyon_trip_options reste partiel pour TCL.
• Indicateurs environnementaux activés seulement si une source est résolue.
• Transport HTTP MCP non inclus (stdio uniquement).

Vie privée / RGPD

• 100 % local, aucune télémétrie. Le serveur tourne sur votre machine ; les profils (domicile/travail), briefings et l’historique Vélo’v restent dans une base SQLite locale.
• Ce qui quitte la machine (mode live uniquement) : les requêtes et coordonnées nécessaires au géocodage et au calcul d’itinéraire sont envoyées aux services concernés (DataGrandLyon, instance Photon de la Métropole, Transitous si activé), soumis à leurs propres politiques.
• Les profils d’exemple (profiles.example.yaml) n’utilisent que des lieux génériques (Bellecour, Lyon 3ᵉ) — aucune donnée personnelle réelle n’est versionnée.

Licence & attribution

Code sous licence MIT (voir LICENSE). Les données proviennent de sources tierces avec leurs propres licences et obligations d’attribution — voir ATTRIBUTIONS.md et docs/data-sources.md.

Projet indépendant, non affilié à la Métropole de Lyon, SYTRAL Mobilités, Keolis-TCL ni JCDecaux. « TCL », « Vélo’v » et les autres noms cités sont des marques de leurs titulaires respectifs, employées ici de façon purement descriptive.

---

<a id="english"></a>

English

Local MCP server aggregating Métropole de Lyon open data behind 10 read-only business tools. Works with any stdio MCP client (Claude Desktop, Cursor, custom agents).

Install

uv sync --all-extras --dev
uv run grand-lyon-mcp db migrate
uv run grand-lyon-mcp doctor
uv run grand-lyon-mcp serve --transport stdio

Credentials via env only (DATAGRANDLYON_USERNAME / DATAGRANDLYON_PASSWORD) — never committed, logged, or returned by tools. Application logs go to stderr; stdout is MCP protocol only. Run without credentials → offline mode (fixtures).

Connect a client

Get a ready-to-paste mcpServers block with make client-config. See docs/mcp-clients.md.

Quality gate

uv run ruff format --check . && uv run ruff check . && uv run mypy src
uv run pytest -m "not live" --cov

Docs & licensing

Architecture, tools, data sources/licenses, operations and troubleshooting under docs/. Attributions in ATTRIBUTIONS.md. Code is MIT; data belongs to its respective providers. Independent project, not affiliated with Métropole de Lyon, SYTRAL, Keolis-TCL or JCDecaux.