linear

Linear

Manage Linear issues, author VantageEx-compatible epics, and interact with the Linear API via MCP or direct GraphQL.

MCP Setup (Preferred)

The Linear MCP server provides tool-based access to Linear. Set up once:

claude mcp add --transport http linear-server https://mcp.linear.app/mcp

Then run /mcp in a Claude Code session to complete OAuth authentication (opens browser).

After setup, use MCP tools directly for all Linear operations. The MCP server handles authentication and provides structured tool interfaces.

For full setup details, troubleshooting, and alternative client configurations, read references/mcp-setup.md.

GraphQL Fallback

When MCP is unavailable (headless environments, scripting, CI), use the GraphQL API directly.

Endpoint: https://api.linear.app/graphql Auth: Bearer token via LINEAR_API_KEY environment variable

# Test connectivity
curl -s -H "Authorization: Bearer $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ viewer { id name email } }"}' \
  https://api.linear.app/graphql

For the full query catalog, read references/graphql-api.md.

The nushell client at scripts/0.1.0/linear.nu wraps common GraphQL operations.

Common Operations

Query an Issue

By key (e.g., MT-686):

query IssueByKey($key: String!) {
  issue(id: $key) {
    id identifier title url description
    state { id name type }
    project { id name }
    labels { nodes { name } }
    attachments { nodes { title url sourceType } }
  }
}

Create an Issue

mutation CreateIssue($teamId: String!, $title: String!, $description: String, $stateId: String, $labelIds: [String!]) {
  issueCreate(input: {
    teamId: $teamId
    title: $title
    description: $description
    stateId: $stateId
    labelIds: $labelIds
  }) {
    success
    issue { id identifier url }
  }
}

Update Issue State

Always fetch team workflow states first to get the exact stateId: