Skip to main content
Glama

aviator-mcp-unofficial

Unofficial Model Context Protocol server for the Aviator MergeQueue REST API. Lets Claude (or any MCP client) inspect and operate your merge queue: see why a PR isn't merging, find which PR broke a batch, queue or dequeue PRs, pause branches for a release freeze, and read or change the queue config.

Not affiliated with, endorsed by, or supported by Aviator Technologies, Inc. "Aviator" is their trademark. This project uses only Aviator's public, documented API.

Tools (14)

Read (no side effects)

Write (changes the real queue)

list_repositories — repos + paused/active

queue_pr — queue a PR (optional skip-line + reason)

get_queue_stats — queued / processing / waiting

dequeue_pr

list_queued_prs — queue contents in order

refresh_or_sync_pr — refresh or sync with base

get_pr_status — by number or branch

set_queue_paused — whole repo or a branch glob

get_bot_pr — PRs inside a batch (draft) PR

backport_pr

get_bisection_status — failed-batch bisection

update_config — replace the YAML config (validated locally first)

get_config — YAML (+ optional change history)

get_analytics — summary of queue metrics

Write tools are annotated destructiveHint: true, so clients can ask for confirmation.

Related MCP server: Cursor Cloud MCP

Install

Requires Python ≥ 3.12.

pip install git+https://github.com/danielorzeata83-a11y/aviator-mcp

Create an API token in Aviator (Settings → API token: an account token, or a personal av_uat_… token).

Claude Code

claude mcp add aviator --env AVIATOR_API_TOKEN=av_uat_xxx -- aviator-mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "aviator": {
      "command": "aviator-mcp",
      "env": { "AVIATOR_API_TOKEN": "av_uat_xxx", "AVIATOR_DEFAULT_ORG": "acme" }
    }
  }
}

Configuration

Variable

Required

Meaning

AVIATOR_API_TOKEN

yes

Bearer token

AVIATOR_API_URL

no

Default https://api.aviator.co; set it for on-prem installs

AVIATOR_DEFAULT_ORG / AVIATOR_DEFAULT_REPO

no

Used when a tool call omits org / repo

Examples

  • "Why isn't acme/api #1240 merging?" → get_pr_status → blocked: merge conflict with main (code 106)

  • "Batch #5001 failed — who broke it?" → get_bot_pr → #1242, required check build_and_test failed

  • "Pause release-* in acme/api for the freeze" → set_queue_paused(branch_pattern="release-*")

  • "Switch to parallel mode, 5 builds" → get_config → update_config with the full edited YAML

A companion Claude skill (skill/aviator-mergequeue) adds workflows, status codes and the config reference. Install it by copying that folder into your Claude skills directory, or zip it and upload it in Claude.

Behaviour notes and limitations

  • Errors are turned into actionable messages (401 token, 403 permission/repo not configured, 404, 400 field list, 429 rate limit). GET requests retry once on 429/5xx; writes are never retried automatically.

  • Large outputs are capped: the config YAML is truncated (max_chars), lists are limited (limit), and analytics return a summary unless include_daily=true.

  • Not covered in v0.1: the GraphQL API, user_actions (Enterprise audit log), and the TestDeck, Releases, Verify and Runbooks APIs.

  • Branch-level pause status can't be read: tested against the live API, GET /api/v1/branches is rejected and the POST form requires paused (it changes state). Pausing/resuming branches works via set_queue_paused.

  • Verified end-to-end against a live Aviator account (Nov 2026): every tool, including queue → merge, a parallel-mode batch, backport, skip-line, sync, branch pause and config update.

  • Live-API quirks handled: affected_targets and a full merge-commit message (title + body) are always sent; analytics times are in minutes.

  • AVIATOR_DEMO=1 runs the server on simulated data (no token, no network) for demos.

Repository layout

Path

What it is

src/aviator_mcp/

The MCP server (server.py tools, client.py HTTP + errors, logic.py validation, demo.py simulated API)

tests/

Unit tests (HTTP mocked with respx)

eval/

20-task evaluation harness on a simulated Aviator world

skill/aviator-mergequeue/

Claude skill: SKILL.md + references

skill/eval/

Skill-triggering evaluation

docs/PORTFOLIO.md

Problem → solution → measured results

Development

pip install -e ".[dev]"
pytest --cov=aviator_mcp          # unit tests (HTTP mocked with respx)
bash eval/oracle.sh               # validates the evaluation harness

License

MIT. API knowledge is derived from Aviator's documentation (github.com/aviator-co/gitbook-docs, MIT).

Available Tools

14 tools
backport_prA
Destructive

Ask Aviator to backport a merged PR onto another branch (it opens a new PR).

Inputs: number (required), target_branch (required), org, repo.

dequeue_prA
Destructive

Remove a PR from the merge queue (also clears its skip-line options).

Inputs: number (required), org, repo.

get_analyticsA
Read-onlyIdempotent

Merge-queue analytics for a date range: time in queue, PRs merged, blocked reasons. Returns a summary; daily rows on request.

Inputs: end, org, repo, start, +2 more.

get_bisection_statusB
Read-onlyIdempotent

Whether Aviator is bisecting a failed batch containing this PR, and the failing bot PR.

Inputs: number (required), org, repo.

get_bot_prA
Read-onlyIdempotent

PRs batched into an Aviator bot (draft) PR. Use it when a batch's CI failed, to see which PRs were in it.

Inputs: number (required), org, repo.

get_configB
Read-onlyIdempotent

Current MergeQueue YAML config of a repo, optionally with change history.

Inputs: org, repo, max_chars, history_end, +2 more.

get_pr_statusA
Read-onlyIdempotent

Merge-queue status of one PR, looked up by number OR branch (exactly one). Includes its batch (bot) PR, if any.

Inputs: org, repo, branch, number.

get_queue_statsA
Read-onlyIdempotent

Live queue depth for a repo: queued, processing and waiting PR counts.

Inputs: org, repo.

list_queued_prsB
Read-onlyIdempotent

PRs currently in the merge queue, in queue order (number, title, author, status).

Inputs: org, repo, limit, base_branch.

list_repositoriesA
Read-onlyIdempotent

List repositories connected to Aviator with paused (whole-repo pause) and active. Branch-level pause state is not readable via Aviator's API.

Inputs: limit.

queue_prC
Destructive

Add a PR to the merge queue (Aviator merges it once CI passes).

Inputs: number (required), org, repo, skip_line, +4 more.

refresh_or_sync_prB
Destructive

refresh: re-evaluate a PR's queue state. sync: update the PR branch with its base branch.

Inputs: action (required), number (required), org, repo.

set_queue_pausedB
Destructive

Pause or resume merging for a whole repo, or only for matching base branches.

Inputs: paused (required), org, repo, branch_pattern, +1 more.

update_configA
Destructive

Replace a repo's MergeQueue YAML config. Call get_config first, edit only what was asked, send the whole file. Parallel mode: merge_rules.merge_mode.type: parallel + merge_mode.parallel_mode.max_parallel_builds / batch_size.

Inputs: yaml_config (required), org, repo.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 14 tools

    Disambiguation4/5

    Most tools target clearly separate concerns (queue ops, PR status, bot/batch inspection, config, analytics, pause). Minor overlap exists between get_bot_pr, get_pr_status, and get_bisection_status, all of which surface batch/bot PR information during failure investigation, and refresh_or_sync_pr bundles two distinct actions into one tool.

    Naming Consistency4/5

    Nearly all tools follow a consistent snake_case verb_noun pattern (get_pr_status, list_queued_prs, queue_pr, dequeue_pr, update_config). The only deviation is the compound-verb refresh_or_sync_pr, which is readable but breaks the single-verb convention.

    Tool Count5/5

    14 tools is well within the well-scoped 3-15 range and each tool maps to a distinct merge-queue operation. No evident filler or redundant tools.

    Completeness4/5

    The surface covers the core lifecycle: queue/dequeue, status inspection, bisection/batch diagnostics, repo listing, queue stats, config get/update, analytics, pause, and backport. Gaps remain around per-PR skip-line/priority options (dequeue mentions clearing them but nothing sets them) and there is no way to inspect individual PR CI checks or batch contents beyond the bot PR summary.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      Enables any MCP client to triage cloud agents, projects, conversations, transcripts, pull requests, and files, including listing agents, reading transcripts, following runs, and sending follow-ups, using an API key or browser sign-in.
      29
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables an MCP client to sign in and inspect workspace-scoped review findings and hosted runs, and to prepare, then start or rerun after explicit confirmation, an existing hosted code review for a pull request. It exposes only concise summaries, never raw diffs, full reports, artifacts, credentials, or prompt text.
      2 npm
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP clients to sign in, list workspaces, and inspect workspace-scoped review findings and hosted runs. It can also prepare and, after explicit user confirmation, start or rerun an existing hosted pull-request review without exposing raw diffs, full reports, artifacts, credentials, or prompt text.
      2 npm
      -