How Do I Let an AI Assistant Validate GTFS Feeds?

By Igor Akimov, maintainer of GTFS Guru

Install gtfs-guru-mcp, the GTFS Guru MCP server, and register it in your assistant with --allow-dir pointing at the folder that holds your feeds. The assistant can then list your feeds, validate them, and explain the results using exact notice totals and real examples from the report.

MCP (Model Context Protocol) is the standard way for an AI client to call local tools. The server runs on your own machine, started by the client. It is read-only: it never writes to a feed, and it can only open files under the folders you allow. It runs the same Rust validator as the browser app and the CLI.

What the server exposes

Four tools:

list_gtfs_feeds: finds ZIP archives and unzipped feeds under the allowed folders and returns the absolute path the other tools take, so the assistant does not have to search your disk. An optional nameContains filter matches names case-insensitively.
validate_gtfs: validates a feed and returns a feed profile, exact totals for each notice code and severity, and up to three concrete examples per group with the file, row, field, message, context values, and a suggested fix where one exists.
explain_gtfs: the same validation payload plus a plain-language explanation built only from deterministic facts about the feed.
get_notice_details: the description, severity and references for one notice code. The same codes are documented for people in the notice code reference.

The totals are counted by the validator, not estimated by the model. When the assistant says a feed has a given number of foreign_key_violation errors, that number comes from the report.

Install the server

Every GitHub release attaches gtfs-guru-mcp archives for Linux (x86_64, x86_64-musl, aarch64), macOS (x86_64, arm64, universal) and Windows (x64). Unpack one and put the binary on your PATH, for example on Linux:

tar -xzf gtfs-guru-mcp-linux-x86_64.tar.gz
sudo install -m 755 gtfs-guru-mcp /usr/local/bin/

With a Rust toolchain you can install it from crates.io instead:

cargo install gtfs-guru-mcp

The Developers section on the home page has a "Connect your AI assistant" dialog that builds the install commands and client config for your operating system.

Connect your assistant

Most clients take the same JSON block. Replace the path with the folder that holds your feeds:

{
  "mcpServers": {
    "gtfs-guru": {
      "command": "gtfs-guru-mcp",
      "args": ["--allow-dir", "/path/to/feeds"]
    }
  }
}

Claude Code: run claude mcp add gtfs-guru -- gtfs-guru-mcp --allow-dir /path/to/feeds, or put the block above in .mcp.json in the project root.
Claude Desktop: Settings, Developer, Edit Config, and add the block to claude_desktop_config.json.
Cursor: ~/.cursor/mcp.json for every project, or .cursor/mcp.json for one.
VS Code: .mcp.json in the workspace, with the top-level key servers instead of mcpServers.
Codex CLI: add a [mcp_servers.gtfs-guru] table with command and args to ~/.codex/config.toml.

A client started from a desktop icon often does not inherit your shell's PATH. If the server does not start, give command the absolute path to the binary. Then ask something like "Which GTFS feeds do I have, and what are the errors in the newest one?"

What stays on your machine

The feed files. The client starts the server locally over stdio; nothing is uploaded to gtfs.guru, and gtfs.guru is not part of the connection.
Everything outside the --allow-dir folders. The server cannot read it.
The network, by default. The server only downloads feeds from public URLs if you start it with --allow-url, and even then it refuses local and private addresses, credentials in URLs, oversized downloads and more than five redirects.

What the server returns to your assistant (totals, the profile, and the example rows) becomes part of your conversation, so it goes wherever your assistant sends its context. Use --notice-examples-per-group 0 to return only the grouped totals and no example rows.

Remote clients over HTTP

For a client that cannot start a local process, the server also speaks stateless Streamable HTTP, protected by a bearer token of at least 32 bytes:

export GTFS_GURU_MCP_BEARER_TOKEN="$(openssl rand -hex 32)"
gtfs-guru-mcp --transport http --bind 127.0.0.1:3000 --allow-dir /path/to/feeds

The endpoint is /mcp. Put TLS in front of it with a reverse proxy before exposing it, and pass the public hostname with --allowed-host. By default the HTTP transport allows 60 authenticated requests per rolling minute, four concurrent validations and 64 KiB request bodies. The MCP setup guide covers every option.

FAQ

Does the AI decide whether my feed is valid?

No. The validator decides, using the same rules and notice codes as the rest of GTFS Guru. The assistant reads the result and can paraphrase it, but the counts and examples come from the report.

Can the assistant fix my feed through MCP?

No. The server is read-only and never writes to a feed. It can return a suggested fix per example, and the CLI's --fix option writes a repaired copy if you want to apply those changes yourself.

Which assistants work with it?

Any MCP client that can start a local stdio server, or connect to an HTTP one. The setup dialog on the home page has ready-made config for Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI and OpenCode.