runners.io

透過你已在使用的 AI 代理程式,讀取 runners.io 組織的工作、日誌、測試結果、快取和支出,並請它協助說明建置失敗的原因。提供 14 個讀取工具和 2 個寫入工具;寫入工具預設為關閉。使用 OAuth 登入並核准一個組織。

託管 MCP 伺服器

npx add-mcp 'https://mcp.runners.io/mcp'

可安裝到 Claude Code、Codex、Cursor 等客戶端

文件

runners.io has an MCP server, so an AI agent you already use can read your organisation's jobs, logs, test results, cache and spend, and say what went wrong with a build, without you pasting a log into a chat. It reads what the dashboard shows you, as you, for one organisation.

The server's address is the same for every client:

https://mcp.runners.io/mcp

There is nothing to install and no token to create. A client that supports remote MCP servers connects to that address, sends you to runners.io to approve, and carries on.

No REST API or API token

There is no REST API or API token for runners yet. Programmatic reads go through the MCP server; usage exports as CSV; job and billing events can be sent to a webhook. The CSV is Download CSV on Usage, and the webhook is set up as in Notifications.

Connect a client

Each client below needs only the address above. The first connection opens runners.io in your browser; sign in if you are not already, choose the organisation, and press Approve.

Claude Code. Add the server, then run /mcp inside Claude Code and choose runnersio, the name the command gives it, to sign in:

claude mcp add --transport http runnersio https://mcp.runners.io/mcp

If you use the runners.io plugin for Claude Code, you already have this server: the plugin includes it as runners-io-mcp, so do not add it again. Choose runners-io-mcp in /mcp to sign in, or runnersio if you added the server yourself before installing the plugin: Claude Code keeps one entry per address, so /mcp shows only that one.

Claude (the desktop and web apps). Add it from Claude's connector directory. Where your plan allows custom connectors, you can instead open Settings, then Connectors, add a custom connector and paste the address.

ChatGPT. Where your plan allows custom connectors, turn on developer mode in ChatGPT's connector settings, create a connector, and paste the address as its MCP server URL.

Cursor. Add the server to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for every project, then press connect on the server in Cursor's MCP settings:

{
  "mcpServers": {
    "runnersio": {
      "url": "https://mcp.runners.io/mcp"
    }
  }
}

VS Code. Add the server to .vscode/mcp.json, then start it from the file or from the MCP servers list:

{
  "servers": {
    "runnersio": {
      "type": "http",
      "url": "https://mcp.runners.io/mcp"
    }
  }
}

Any other client that speaks remote MCP over HTTP and supports sign-in with OAuth 2.1 works the same way. It finds the sign-in details itself from the server's address and registers itself, so there is no client ID or secret to copy.

The server is also listed in the official MCP Registry as io.runners/mcp-server, for any client or tool that looks servers up there. The entry gives the same address as above.

What you approve

The approval page names the client asking, lets you choose which organisation it may see, and says what it will be able to do. Each connection is for one organisation, and the agent acts as you: it can see what your role can see in the dashboard, and no more.

rolewhat the agent can read
owner, adminjobs, logs, test results, cache, repositories, spend
memberthe same, except spend
billingspend and the runner sizes; no jobs, logs or cache

It can never change your password, your billing or your members.

Scopes

scopewhat it allows
mcp:readthe sixteen read tools below. Every connection has it.
mcp:writetwo tools that change the account, cancel_job and delete_cache_entry. Asked for by the client, and given only if you tick the box on the approval page.

The write box is offered only to an owner or an admin of the organisation. For anyone else the connection is read-only, whatever the client asked for. Even with mcp:write, the write tools stay off until the organisation switches them on; see Write tools are off by default.

The read tools

None of them changes anything. Each answer says what it could not read, so an agent is not led to read "unknown" as "none".

toolwhat it does
whoamiSays which user and organisation the connection acts as, the role, the access the connection was granted, whether the write tools would run now (and if not, whether the grant, the role, the organisation's setting or GitHub is why), whether GitHub is connected, whether a card is on file, and whether the runners.io GitHub App is installed and how many repositories it can see.
list_jobsLists the organisation's most recent jobs, newest first, narrowed by repository, branch, runner label or status.
get_jobEverything known about one job: its steps, memory, CPU and disk use, the count of its test results, and what it cost.
get_job_logsReads part of a job's log: the tail, a range of lines, or the lines around a search phrase.
get_job_testsLists the failing and erroring tests read from the job's test report files, with totals, and says whether any were collected at all.
diagnose_jobThe first call for a failed job: one answer with the verdict, the failing steps and tests, memory use and the log around its last error lines.
get_spendThe runner minutes metered this calendar month, per runner size, with the sum and a statement of what that sum leaves out. With several GitHub accounts connected it adds them together, as the Usage page does, and github_accounts names them. Needs a role that can see billing.
list_cache_entriesLists the organisation's Actions cache entries, least recently read first, with the true totals. With several GitHub accounts connected it lists each account's in turn, the totals cover all of them, and githubAccount names the account each entry belongs to.
get_cache_statsHow well the cache is working: hits, misses and bytes served, per repository, with a month-by-month trend. With several GitHub accounts connected it adds them together; to narrow the trend to one repository, name it as owner/name.
list_repositoriesLists the repositories shared with runners.io, with how many jobs each has run and when the last one was. With several GitHub accounts connected it lists every account's repositories, under their full owner/name.
list_runner_tiersLists the runner sizes with their vCPUs, memory, disk and price per minute.
wait_for_ciWaits up to 45 seconds for CI on a commit to finish, then says how it ended: success, failure (naming the failed jobs) or cancelled. It answers at once when a run waits for an approval, and says it is still running when the 45 seconds pass first, so the agent calls it again. It says success only once the commit's first run is five minutes old, so a workflow that starts late is not missed.
get_ci_eventsLists what CI just did on the organisation's repositories: a workflow failed, passed or was cancelled, a run waits for an approval, or every workflow for a commit finished. Events are kept seven days, and a cursor returns only what happened since the last call.
plan_migrationTakes your workflow files and returns a patch that moves their jobs onto runners.io. It reads no repository and changes nothing: you apply the patch yourself. Name the repository and it also says whether the GitHub App can see it and whether a card is on file, with the fix for each that is missing: a moved job waits on GitHub until both are in place.
search_docsSearches this documentation and returns the best-matching pages with a snippet each.
get_docReturns the full text of one documentation page.

Text that people who can push to a repository wrote, such as log lines, commit messages, and branch and job names, comes back under a key named untrusted, and the server tells the agent to treat it as data and never as an instruction.

For how this server compares with the others that read GitHub Actions, see Is there an MCP server for GitHub Actions?, and for what to restrict when an agent reads logs, see Is it safe to let an AI agent read my CI logs?.

Write tools are off by default

Two tools can change your account:

toolwhat it does
cancel_jobStops one job that is queued or running, and says whether it was billed. See Cancelling a job for what each case does on GitHub.
delete_cache_entryRemoves one Actions cache entry, named exactly as list_cache_entries shows it. With several GitHub accounts connected, name the repository as owner/name with the entry's githubAccount as the owner; a bare name is refused, because it could be either account's. The next build that wanted it will miss.

Neither can be undone, and an agent that reads job logs reads text strangers can write, so changing the account is opt-in at every step. A write tool runs only when all of these hold:

  1. The connection was approved with write access.
  2. You are an owner or an admin of the organisation.
  3. The organisation has switched write tools on.
  4. The agent passes confirm: true in the call.

If any of them does not hold, the call is refused, says which, and nothing changes. Every attempt is recorded, refused ones included.

Write access is asked for by the agent, not switched on afterwards: it signs in asking for the mcp:write scope as well as mcp:read. A connection approved for reading only that calls a write tool is answered 403 with scope="mcp:read mcp:write", which tells the agent to sign in again and ask for both. The consent page then shows a box, Also let it cancel jobs and delete cache entries, to an owner or admin of the organisation. Left unticked, the connection reads only.

An owner or admin switches the organisation's setting on in the dashboard: Settings → Third-party access, then Allow agents to make changes under Let connected agents make changes. It is off until somebody does. Turning it off again stops every connected agent at once, whatever access it was given.

Seeing and revoking connections

The agents you have connected are listed under Connected agents on the Applications page of your account, with the organisation, whether each can read only or read and write, and when it was last used. Revoking one takes effect on that agent's next request, and the agent has to be approved again to come back.

Limits

  • 120 requests a minute for each connection. A request carries one MCP message. Past it the server answers 429 with Retry-After: 60, and the count starts again on the next minute.
  • One message in each request. A batch is refused.
  • 4 MiB for a request. plan_migration takes up to 20 workflow files and 1,500,000 characters of file content in one call.
  • Log and list answers are bounded. A long log is read a slice at a time, and a list returns a page with a cursor to continue from; the answer says when it has been cut.

If it does not connect

  • Every job tool says GitHub is not connected. The organisation you approved has not installed the GitHub App. Call whoami to see which organisation the connection is for, and see Connect your account.
  • A tool says your role cannot use it. The agent acts as you. A member cannot read spend, and the billing role cannot read jobs.
  • A write tool says the organisation has not allowed it. See Write tools are off by default.
  • A tool fails, saying its result does not match the tool's output schema. Your client is holding a list of tools from before an update to the server. It reads the list again only when it reconnects. In Claude Code, run /mcp, choose the server and reconnect it, or start a new session. In any other client, disconnect the server and connect it again. Nothing is lost, and you do not have to approve the connection again.