Skip to main content
Lists file paths in a repository at a branch, tag or commit, optionally only under one directory. Use it to find what to read with github_get_file.

​
Authentication and enablement

Requires a connected native GitHub integration (mcp:github) — a first-party GitHub App connection, not Composio. The connector is shown on Trail and to Nanonets superadmins; it is hidden from Nanonets customers during rollout. Connecting opens GitHub’s install page for the Trail GitHub App, where the user picks the account and either all repositories or only selected ones. Tools act as the app’s bot account through short-lived installation tokens — not as the connecting user — and reach only the repositories of that installation. To change which repositories are included, edit the installation on GitHub (the account’s or organization’s installed GitHub Apps settings) or reconnect. If an organization owner still has to approve the app, calls fail until they do; if the app was uninstalled or suspended, calls fail until GitHub is reconnected. Relies on the app’s Contents (read) permission.

​
Inputs

  • owner (required): repository owner (user or organization).
  • repo (required): repository name.
  • ref (optional): branch, tag or commit SHA. Default: the repository’s default branch.
  • path_prefix (optional): only paths starting with this, e.g. dags/. Include the trailing slash to match a directory exactly (dags also matches dags_old/).
  • limit (optional): max paths to return (1–2000). Default 500.

​
Output

  • ref: the ref listed (the default branch’s name when ref was omitted).
  • files: file paths (directories and submodules are not listed).
  • total: how many files matched path_prefix.
  • truncated: true when more paths exist than were returned — either limit was hit or GitHub cut the listing short for a very large repository (then total is also incomplete).

​
Limits and side effects

  • Read-only.
  • owner/repo must be plain GitHub names (letters, numbers, ., _, -); anything else is rejected before any API call.
  • Lists the whole tree recursively in one GitHub call, then filters; for very large repositories GitHub returns only part of the tree.

​
Expected errors

  • No GitHub connection, a connection still waiting for an organization owner to approve the app, or an app that was uninstalled or suspended (reconnect GitHub).
  • Invalid owner/repo format.
  • GitHub API errors surface as the tool’s error, rewritten to say what to fix: not found or no access to that repository (404 — check which repositories the installation includes), the repository is empty (no commits yet, HTTP 409), rate limit reached with the retry time (including GitHub’s secondary limits, which ask for a one-minute wait), rejected app credentials (reconnect).