convez.ai
MCP ServerIntegração & APIsIntermediário
agileandy

Linear API GraphQL Skill

agileandy/linear-api

GraphQL CLI para Linear com webhooks, ciclos e admin — zero custo de token quando inativo

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP Server Python que expõe a API GraphQL do Linear através de um CLI fino, com cobertura completa incluindo webhooks, ciclos e funções admin. Substitui o MCP padrão com descoberta progressiva para reduzir consumo de tokens e oferecer controle total sobre queries.

Instalação

$npx convez-ai agileandy/linear-api

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
0

Casos de uso

  • Integrar Linear com agentes Claude para automação de workflows com webhooks
  • Gerenciar ciclos, estados de workflow e relações de issues via GraphQL
  • Consultar audit log e realizar ações admin sem overhead de MCP tradicional

Veredito

Solução técnica sólida para integração Linear em agentes Claude. A abordagem de skill GraphQL reduz custos de token significativamente e preenche lacunas críticas do MCP (webhooks, admin). Recomendado para equipes que usam Linear como sistema central de dados.

README

A tradução para o português deste README ainda está na fila.

linear-api

A Claude Code / Cowork skill that talks to Linear's GraphQL API directly — instead of carrying ~40 MCP tool schemas in context every turn. Progressive discovery: load SKILL.md once, load only the reference file the current task needs, compose GraphQL through a thin Python CLI.

Python 3.11+ License: MIT Tests: 24 passing

TL;DR

git clone https://github.com/agileandy/linear-api.git
cd linear-api
uv sync
cp .env.example .env                 # edit: paste your Linear API key
uv run python scripts/linear.py query 'query { viewer { id name email } }'

That's it — you can query Linear. Read SKILL.md for the conceptual orientation, references/common-queries.md for 18 worked GraphQL operations covering the full Linear MCP surface, references/mutations-cheatsheet.md for the surface the MCP can't touch (webhooks, cycles, workflow states, relations, templates, audit log).

Why a skill instead of the MCP

Three reasons, in order of how often they bite:

  1. Coverage. The Linear MCP can't manage webhooks, cycle / workflow-state mutations, issue relations, templates, custom views, audit log, or admin surface. The API can. That gap is the whole reason this exists. Without webhooks, every Linear-aware agent reduces to polling.
  2. Token cost. The MCP loads ~40 tool schemas into the agent's context every turn, whether the agent touches Linear or not. This skill loads SKILL.md (~120 lines) only when the routing layer says a Linear task is starting, and a reference file (~150–650 lines) only for the part of Linear the task touches. Net per-turn cost when Linear is dormant: zero.
  3. Control. GraphQL only returns the fields you ask for. No fixed tool shapes — if a workflow needs a field MCP didn't expose (or a new field Linear ships next week), you ask for it.

The trade-off: the agent has to learn query composition rather than calling pre-baked tools. references/common-queries.md is the one-time price for that — 18 worked examples that cover the MCP-parity surface so the agent only composes from scratch when it goes off-piste.

Coverage at a glance

SurfaceLinear MCPthis skill
Issues, comments, projects (CRUD)✅✅
Initiatives, milestones, documents, attachments✅✅
Cyclesread onlyfull CRUD + shiftAll, startUpcomingCycleToday
Workflow statesread onlyfull CRUD
Issue relations (blocks / duplicate / related)❌✅
Reactions on issues / comments / updates❌✅
Notification subscriptions❌✅ (no delete — toggle active: false)
Templates, custom views, favorites❌✅
Webhooks (CRUD + secret rotation)❌✅
Audit log query❌✅ (auditEntries filter)
User admin (changeRole, suspend, etc.)❌✅ (admin scope only)
Org invites, domain claims, integration mgmt❌✅

Status

  • Phase 0 (spike) — ✅ done. Live-tested CLI against a real workspace.
  • Phase 1 (MCP parity) — ✅ done. SKILL.md, foundational refs, 18 worked GraphQL ops.
  • Phase 2 (gap five) — ✅ done. Full webhooks reference, full mutations cheatsheet for cycles / states / relations / templates / admin.
  • Phase 3.1 (OAuth bot identity) — ✅ done via client_credentials grant. Comments and writes attribute to a registered bot, not to the developer.
  • Phase 3 backlog — tracked in Linear:
    • AGI-88 — rate-limit-aware retry helper
    • AGI-89 — schema introspection cache
    • AGI-90 — structured mutation logging / telemetry

Install

You can use this repo three ways. Pick whichever matches how you want it surfaced.

1. Standalone (just the CLI)

git clone https://github.com/agileandy/linear-api.git
cd linear-api
uv sync
cp .env.example .env                 # then edit

The CLI runs as uv run python scripts/linear.py …. Reference docs and example scripts are at references/ and scripts/examples/.

2. As a Claude Code skill (recommended for agent use)

Make the skill discoverable so an agent loads SKILL.md automatically when a Linear task starts.

# Project-scoped install (visible only inside one project)
mkdir -p .claude/skills
ln -s "$(pwd)" .claude/skills/linear-api

# Or global install (visible across every project)
mkdir -p ~/.claude/skills
ln -s "$(pwd)" ~/.claude/skills/linear-api

The skill's name and description (from SKILL.md's frontmatter) become discoverable via Claude Code's skill list. The agent loads SKILL.md only on first use; per-domain reference files only when a task touches that surface. That progressive-discovery pattern is the whole reason this is cheaper in tokens than the Linear MCP.

3. As a slash command

The .claude/commands/linear.md file in this repo defines a /linear slash command for working assigned issues end-to-end (fetch → In Progress → implement → Done → comment).

# Symlink globally
ln -s "$(pwd)/.claude/commands/linear.md" ~/.claude/commands/linear.md

Then /linear, /linear AGI-23, or /linear AGI-23, AGI-26 from any Claude Code session.

Auth — pick your path

Three options, simplest first. Full walkthrough including OAuth-app setup and gotchas in references/auth.md.

Option A — Personal API key (simplest)

Linear → Settings → API → Personal API keys → Create. Paste the lin_api_… token into .env:

LINEAR_API_KEY=lin_api_xxxxxxxx

Acts as you. ~2,500 req/hr. Use for personal scripts, dev work.

Option B — Bot identity via client_credentials grant (recommended for autonomous use)

Comments and writes show the bot's name in Linear's UI and audit log instead of yours. ~30-day token, idempotent re-mint, 5,000 req/hr.

# 1. Linear → Settings → API → OAuth applications → Create new application.
#    Toggle "Client credentials" ON. Save. Copy Client ID + Secret.
# 2. Paste into .env:
#       LINEAR_OAUTH_CLIENT_ID=...
#       LINEAR_OAUTH_CLIENT_SECRET=...
# 3. Mint the bot token:
uv run python scripts/client_credentials_token.py
# 4. Verify:
uv run python scripts/linear.py query 'query { viewer { name displayName } }'
#    → returns the bot's identity, not yours

Re-run the mint script before each ~30-day expiry. Cron line in references/auth.md.

Option C — OAuth authorization_code dance (multi-tenant distribution)

For when you ship the skill to other people who'll install it in their own workspaces. Browser-based consent flow with actor=app URL parameter. Uses 24h access tokens with rolling refresh.

uv run python scripts/oauth_dance.py --write-env       # initial install (browser opens)
uv run python scripts/oauth_refresh.py                 # cron-able, runs before each 24h expiry

Caveat from live testing: Linear's actor=app is sometimes silently downgraded to user-scoped tokens on the auth-code path — Option B is more reliable for solo use. Full notes in references/auth.md.

CLI

linear.py query     <doc-or-file> [--variables JSON|@file.json]
linear.py mutation  <doc-or-file> [--variables JSON|@file.json]
linear.py introspect <TypeName>

<doc-or-file> is either an inline GraphQL string or a path to a .graphql file.

Rate-limit (x-ratelimit-*) and complexity (x-complexity) headers go to stderr after every call. The CLI raises and exits non-zero on HTTP 429 with retry-after in the message — see references/rate-limits.md for the retry pattern.

Worked example

# 1. Find the team UUID.
uv run python scripts/linear.py query \
  'query { teams(filter: { key: { eq: "AGI" } }) { nodes { id key } } }'

# 2. Create an issue. Priority 2 = High.
uv run python scripts/linear.py mutation \
  'mutation Create($input: IssueCreateInput!) {
     issueCreate(input: $input) {
       success
       issue { identifier title url }
     }
   }' \
  --variables '{"input": {
     "teamId": "a57f5901-…",
     "title": "auth: 401 on token refresh",
     "priority": 2
   }}'

Three calls, ~8 complexity points total. Every common operation has a copy-paste-ready snippet in references/common-queries.md.

Reference docs

Six files under references/. Load only what the current task needs.

FileLoad when the task is about…
auth.mdToken setup, OAuth flows, scope cheatsheet, revocation
schema-summary.mdEntity model, identifiers, pagination, filtering, soft / hard delete semantics
rate-limits.md429s, complexity errors, observed limits, retry strategy
common-queries.md18 worked GraphQL ops covering the MCP-parity surface
webhooks.mdSubscription mgmt, signing, delivery semantics, common pitfalls
mutations-cheatsheet.mdThe gap five — cycles, workflow states, relations, templates, admin

Example scripts

uv run python scripts/examples/list_my_issues.py
uv run python scripts/examples/create_issue.py --team-key AGI --title "..." --priority 2
uv run python scripts/examples/paginate_issues.py --team-key AGI
uv run python scripts/examples/subscribe_webhook.py \
  --url https://your-receiver.example.com/linear \
  --label "triage agent" --resource-types Issue Comment --team-key AGI

These exist to demonstrate patterns (read, write-then-read, cursor pagination, webhook provisioning), not to enumerate every operation. For breadth, load references/common-queries.md.

Token-cost comparison

Concrete data for the "why this beats MCP" claim. Numbers are approximate, calibrated against Anthropic's tokeniser.

ScenarioLinear MCPthis skill
Linear-irrelevant turn (e.g. frontend work)~2,000 tokens (40 tool schemas always loaded)0 tokens (skill not loaded)
First Linear-relevant turn~2,000 tokens~1,200 tokens (SKILL.md) + ~1,500 (one reference file)
Subsequent Linear turns same task~2,000 tokens0 tokens (already in context)
Coverage of webhooks / cycle mutations / admin❌ unsupported✅ via references/mutations-cheatsheet.md (~3,500 tokens, loaded only when needed)

Net: a project that touches Linear 10% of the time saves ~80% of the per-turn token cost vs the MCP. A project that never touches Linear saves 100%.

Project layout

linear-api/
├── SKILL.md                          # lean entry point — agent's first read
├── README.md                         # this file
├── LICENSE                           # MIT
├── pyproject.toml                    # httpx, python-dotenv (runtime); pytest, respx (dev)
├── .env.example                      # auth template
├── .claude/
│   └── commands/
│       └── linear.md                 # /linear slash command — works assigned issues
├── references/
│   ├── auth.md                       # personal key vs OAuth, scopes, revocation
│   ├── schema-summary.md             # entity model, identifiers, pagination, soft/hard delete
│   ├── rate-limits.md                # observed limits, complexity examples, retry pattern
│   ├── common-queries.md             # 18 worked GraphQL ops — full MCP-parity surface
│   ├── webhooks.md                   # subscription mgmt (resource types, signing, delivery)
│   └── mutations-cheatsheet.md       # the gap five — cycles, states, relations, templates, admin
├── scripts/
│   ├── linear.py                     # GraphQL CLI (query / mutation / introspect)
│   ├── client_credentials_token.py   # ⭐ recommended: mint a 30-day bot token
│   ├── oauth_dance.py                # multi-tenant install flow (browser dance)
│   ├── oauth_refresh.py              # rolling refresh for the dance's 24h tokens
│   └── examples/
│       ├── list_my_issues.py
│       ├── create_issue.py
│       ├── paginate_issues.py
│       └── subscribe_webhook.py
├── tests/
│   └── test_linear_client.py         # respx-mocked unit tests — never hit Linear
└── docs/
    ├── HANDOFF.md                    # original build brief
    └── Linear-API-Integration-Plan.md  # design rationale + MCP gap analysis

Development

Tests

uv run pytest                 # mocked — never touches Linear; safe in CI

24 mock tests cover the GraphQL transport, header logging, auth-mode switching, the 429 / GraphQL-error paths, the OAuth dance and refresh shapes, and the client_credentials mint shape.

Adding new operations

  1. Run scripts/linear.py introspect <TypeName> to see the input shape.
  2. Compose the GraphQL document.
  3. Add a snippet to the relevant references/*.md so it's there next time.
  4. (Optional) Add a worked example script if it demonstrates a pattern (not just an additional read or write).

Contributing

PRs welcome. Conventions:

  • Tests are mocked, never live. tests/test_linear_client.py uses respx to stub httpx. Don't introduce live tests — they leak rate-limit budget and break CI.
  • Reference files are the source of truth for "how to do X with Linear." If you add a new GraphQL op, the snippet goes in references/. The example scripts demonstrate patterns, not coverage.
  • Trunk-based dev. Cut a feature branch per outcome, ff-merge into main when done.
  • Follow the docs gotchas. The "live findings" sections in references/auth.md, rate-limits.md, and mutations-cheatsheet.md are not stylistic preferences — they're things that bit during the build.

Project history

  • docs/HANDOFF.md — the original build brief.
  • docs/Linear-API-Integration-Plan.md — the design doc + gap analysis vs the Linear MCP. Worth reading if you want to understand why the project is shaped the way it is.
  • Git log — phase-by-phase commit history. Each commit's message has the live-test findings that drove the changes.

License

MIT. See LICENSE.

Acknowledgements

Built by Andy Spamer in collaboration with Claude (Anthropic). The Phase 0 spike, MCP-parity reference set, gap-five mutations, and OAuth bot-identity work were all live-validated against a real Linear workspace before each commit landed — see the per-commit messages on main for the live-test findings that shaped the docs.

Ver o original no GitHub

Bom para

Relacionados