Linear API Setup for Cursor AI Agents

Version: 1.0
Date: January 30, 2026
Owner: AI Team

1. Purpose

This guide enables Cursor AI agents to create, update, and manage Linear tickets programmatically. Linear is our project management tool for tracking tasks and issues.

1b. Operator workflows (Linear Agent in-app)

Not MCP-specific—how humans and the in-product Linear Agent run repeatable prompts:

Daily briefing & triage Skills: Copy-paste prompts and deep links live in linear-agent-daily-briefing.md — two focused Skills (Daily briefing vs Triage digest), default stale/horizon parameters, and a redacted example.
Workspace vs personal guidance: Workspace AI / settings apply org-wide; Agent personalization (Skills, personal guidance) is per user. Keep workspace guidance aligned with ticket and label norms below.
Labels when agents create work: Use ai-assignable and human-only per linear-labels-ai-human.md.

2. Project and Ticket Standards (Required for Agents)

Before creating or updating any Linear issue via MCP, agents must:

Follow the ticket format in linear-ticket-generation-from-transcript.md:
- Title: Start with a verb (“Add…”, “Fix…”, “Investigate…”); avoid vague titles.
- Description: Use the exact template: Context, Goal, Scope (In scope / Out of scope), Acceptance Criteria, Notes/Constraints, Open Questions.
Make ordering visible when creating multiple tickets (e.g. for a plan or project):
- Do not put every ticket in Backlog with no indication of sequence. Use one or more of:
  - Labels (e.g. Phase 1, Phase 2, or team capability labels) so the team can sort/filter by phase or type. For AI vs human: use ai-assignable and human-only per linear-labels-ai-human.md.
  - State (e.g. move the first ticket to “Ready for Work” or “ToDo in Cycle” so “what to work on first” is clear).
  - blockedBy to link dependencies; keep tickets small and ordered.
Search before creating to avoid duplicates (see ticket-generation playbook Step 2).

Cursor rule .cursor/rules/linear-mcp-ticket-standards.mdc (repo root) enforces that agents read and apply these guidelines when using Linear MCP.

3. Cursor MCP Integration (Preferred)

Cursor has a built-in Linear MCP (Model Context Protocol) integration that provides direct access to Linear.

Available MCP Tools

Tool	Description
`user-linear-list_issues`	List issues with filters
`user-linear-get_issue`	Get issue details by ID
`user-linear-save_issue`	Create new issue (use this for creating issues; preferred over create_issue)
`user-linear-update_issue`	Update existing issue
`user-linear-list_teams`	List all teams
`user-linear-list_projects`	List projects
`user-linear-list_comments`	Get issue comments
`user-linear-create_comment`	Add comment to issue

Example: Create Issue via MCP

The Cursor agent should use save_issue when creating new issues. Example:

user-linear-save_issue
  title: "My Task Title"
  team: "Platform"
  description: "Task description in markdown"
  assignee: "me"
  priority: 2  # 1=Urgent, 2=High, 3=Normal, 4=Low

4. Manual API Access (When Needed)

Credentials Location

1Password:

Vault: Employee (personal API keys)
Item: Search for “Linear API” or “Linear Personal API Key”

Environment Variable:

LINEAR_API_KEY=lin_api_xxxxx

GraphQL API

Linear uses GraphQL. Base URL: https://api.linear.app/graphql

Example: List Teams

curl -X POST https://api.linear.app/graphql \
  -H "Authorization: ${LINEAR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ teams { nodes { id name } } }"}'

Example: Create Issue

curl -X POST https://api.linear.app/graphql \
  -H "Authorization: ${LINEAR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreateIssue($input: IssueCreateInput!) { issueCreate(input: $input) { success issue { id identifier url } } }",
    "variables": {
      "input": {
        "title": "My Task",
        "teamId": "team-uuid-here",
        "description": "Task description"
      }
    }
  }'

5. Common Cursor Agent Workflows

Create Issue with Branch Name

1. Create issue: user-linear-save_issue
2. Response includes gitBranchName
3. Create branch: git checkout -b {gitBranchName}

Link PR to Issue

Include issue identifier in commit/PR:

Commit message: feat: ... (AI-745)
PR body: Resolves: AI-745

Update Issue Status

user-linear-update_issue
  id: "AI-745"
  state: "In Progress"  # or "Done", "In Review", etc.

6. Team Reference

Common teams in our workspace:

Team	Use For
Platform	Internal platform, data engineering, AI, and delivery work (consolidated from former Data Platform, AI Team, and Delivery)
Operations	Ops and internal processes
Sales	Sales-related tasks

7. Priority Mapping

Value	Name	Use For
1	Urgent	Blockers, critical bugs
2	High	Important, time-sensitive
3	Normal	Standard tasks
4	Low	Nice-to-have, backlog

8. API Reference

GraphQL Playground: https://api.linear.app/graphql
API Docs: https://developers.linear.app/docs
MCP Integration: Built into Cursor

9. Version History

v1.0 (January 30, 2026) — Initial documentation

Brainforge Knowledge

Explorer

linear-api-setup