Goal

Create, update, and manage Linear issues from source documents (Obsidian notes, markdown files, Slack threads, etc.) using the Linear MCP integration.

Prerequisites

•Linear MCP must be connected — the user-linear-* tools must be available
•
If Linear MCP is not available, guide the user to set it up:
1. •Open Cursor Settings (Cmd+Shift+J)
2. •Go to MCP section
3. •Add Linear with config: {"command":"npx","args":["-y","mcp-remote","https://mcp.linear.app/mcp"]}
4. •Authenticate via the browser OAuth flow

Workflow: Creating issues from a document

Step 1 — Identify the source section

When given a document to extract issues from:

•Read the specified file/section
•Look for checkbox items (- [ ] ...) that represent tasks to create
•Extract the bolded text at the start of each item as the basis for the issue title
•Use the rest of the text as the issue description

Step 2 — Plan before creating

Always present a plan before creating issues:

•Show a table with: proposed title, description summary
•Wait for user approval before proceeding
•Allow user to adjust titles or skip items

Example format:

code

| # | Proposed Title | Description (Summary) |
|---|----------------|----------------------|
| 1 | Fix login bug | Users can't log in when... |
| 2 | Add dark mode | Support dark mode toggle in settings... |

Step 3 — Improve titles when needed

When converting checkbox items to issue titles:

•If the item has bolded text at the start, use that as the title basis
•If no bold text exists, create a clear, actionable title from the content
•
Titles should be:
- •Imperative or descriptive (e.g., "Fix X", "Add Y", "X is broken")
- •Concise but specific (avoid vague titles like "Bug fix")
- •Sentence case (capitalize first word only)

Step 4 — Format descriptions

Issue descriptions should include:

•Current behavior (if it's a bug)
•Expected behavior
•Implementation notes (if provided in source)
•References/links (if any URLs are mentioned)

Use markdown formatting (bold, lists, code blocks) for clarity.

Step 5 — Create issues in batches

•Use user-linear-create_issue for each issue
•Required fields: title, team, and optionally project
•Call multiple create operations in parallel when possible (batch 5-6 at a time)
•Collect all created issue IDs and URLs

Step 6 — Report results

After creation, provide a summary table:

code

| Issue | Title | Link |
|-------|-------|------|
| ARD-101 | Fix login bug | [View](https://linear.app/...) |

Common Linear MCP operations

Finding teams and projects

code

user-linear-list_teams          # Get all teams
user-linear-list_projects       # Get all projects (optionally filter by team)
user-linear-get_project         # Get project by name or ID

Creating issues

code

user-linear-create_issue
  - title: string (required)
  - team: string (required) — team name or ID
  - project: string (optional) — project name or ID
  - description: string (optional) — markdown supported
  - priority: number (optional) — 0=None, 1=Urgent, 2=High, 3=Normal, 4=Low
  - labels: string[] (optional) — label names or IDs
  - assignee: string (optional) — user name, email, or "me"

Updating issues

code

user-linear-update_issue
  - id: string (required) — issue ID
  - state: string (optional) — e.g., "canceled", "done", "in progress"
  - (all other fields from create_issue are also available)

Other useful operations

code

user-linear-list_issues         # Search/filter issues
user-linear-get_issue           # Get issue details by ID
user-linear-create_comment      # Add comment to an issue
user-linear-list_issue_labels   # Get available labels
user-linear-list_issue_statuses # Get available statuses for a team

Notes

•Linear MCP cannot permanently delete issues — use state: "canceled" to archive
•Issues are created in "Backlog" status by default
•Each issue gets an auto-generated git branch name (e.g., tim/ard-123-fix-bug)
•The MCP connection may occasionally fail — retry or restart Cursor if needed