---

name: linear description: Interacting with Linear issues, projects, and teams. Use when creating issues, updating issues, querying issues, managing projects, working on tasks, discussing backlogs, or any interaction with Linear. allowed-tools:

• mcp__linear
• WebFetch(domain:linear.app)
• Bash

---

Linear

Tools and workflows for managing issues, projects, and teams in Linear.

Tool Selection

Choose the right tool for the task:

1. MCP tools - Use for simple operations (create/update/query single issues, basic filters)
2. SDK scripts - Use for complex operations (loops, bulk updates, conditional logic, data transformations)
3. GraphQL API - Fallback for operations not supported by MCP or SDK

Conventions

Issue Status

When creating issues, set the appropriate status based on assignment:

• Assigned to me (assignee: "me"): Set state: "Todo"
• Unassigned: Set state: "Backlog"

Example:

Copy// Issue for myself
await linear.create_issue({
  team: "ENG",
  title: "Fix authentication bug",
  assignee: "me",
  state: "Todo"
})

// Unassigned issue
await linear.create_issue({
  team: "ENG",
  title: "Research API performance",
  state: "Backlog"
})

Querying Issues

Use assignee: "me" to filter issues assigned to the authenticated user:

Copy// My issues
await linear.list_issues({ assignee: "me" })

// Team backlog
await linear.list_issues({ team: "ENG", state: "Backlog" })

Labels

You can use label names directly in create_issue and update_issue - no need to look up IDs:

Copyawait linear.create_issue({
  team: "ENG",
  title: "Update documentation",
  labels: ["documentation", "high-priority"]
})

Label Lookup: Labels can exist at the workspace level or team level. When searching for labels, check both:

1. Workspace labels: list_issue_labels() (no team filter)
2. Team labels: list_issue_labels({ team: "TEAM" })

If a label isn't found at the workspace level, check the team before concluding it doesn't exist.

SDK Automation Scripts

Use only when MCP tools are insufficient. For complex operations involving loops, mapping, or bulk updates, write TypeScript scripts using @linear/sdk. See sdk.md for:

• Complete script patterns and templates
• Common automation examples (bulk updates, filtering, reporting)
• Tool selection criteria

Scripts provide full type hints and are easier to debug than raw GraphQL for multi-step operations.

GraphQL API

Fallback only. Use when operations aren't supported by MCP or SDK. See api.md for documentation on using the Linear GraphQL API directly.

Ad-Hoc Queries

Use scripts/query.ts to execute GraphQL queries:

CopyLINEAR_API_KEY=lin_api_xxx node scripts/query.ts "query { viewer { id name } }"

If LINEAR_API_KEY is not provided to the Claude process, inform the user that GraphQL queries cannot be executed without an API key.

Opening Issues in the Desktop App

Use the linear:// URL scheme to open issues in the native Mac app instead of the browser:

Copy# Replace https://linear.app with linear:// in any Linear URL
open "linear://team-slug/issue/ENG-123"

The desktop app must be installed. When given an issue identifier (e.g., ENG-123), construct the URL using the team's workspace slug and issue identifier.

Reference

• Linear MCP: https://linear.app/docs/mcp.md
• GraphQL API: See api.md