Using Claude with Linear for Project Management: Setup and Best Practices

Linear is how modern teams track work. The Linear MCP server makes it even more powerful by connecting Claude's intelligence to your issue database. No more manually creating tickets, formatting descriptions, or searching for related issues. Claude handles it. ## Why Integrate Claude with Linear Typical Linear workflow: - Someone reports a bug in Slack - You create a Linear issue manually - Copy context from Slack, logs, screenshots - Format everything nicely - Set priority, assignee, project - Link related issues - 5-10 minutes per issue With Claude integration: - "Create a Linear issue for this bug" + paste context - Claude creates formatted issue with: - Clear title and description - Appropriate labels and priority - Links to related issues - Suggested assignee - 30 seconds The integration also enables intelligent querying, status reporting, and project insights. ## Setup: Linear MCP Server ### Prerequisites - Claude Code installed - Linear workspace access - Node.js 16+ installed - Admin or member role in Linear ### Step 1: Generate Linear API Key 1. Go to Linear Settings → API 2. Click "Create new key" 3. Name it "Claude MCP" 4. Copy the API key (starts with `lin_api_`) **Note:** Keep this key secure - it has full access to your Linear workspace. ### Step 2: Install Linear MCP Server ```bash npm install -g @anthropic-ai/mcp-linear ``` ### Step 3: Configure Claude Code Add to `~/.config/claude/mcp.json` (macOS/Linux) or `%APPDATA%\Claude\mcp.json` (Windows): ```json { "mcpServers": { "linear": { "command": "mcp-linear", "env": { "LINEAR_API_KEY": "your_api_key_here" } } } } ``` ### Step 4: Verify Connection Restart Claude Code and ask: "What projects do we have in Linear?" Claude should list your Linear projects. ## Core Capabilities ### 1. Create Issues "Create a bug report: Users are seeing 500 errors on the checkout page. Started this morning around 9am PST. Error logs show timeout connecting to payment service." Claude: - Creates issue with descriptive title: "Payment service timeout causing checkout 500 errors" - Formats description with: - Problem statement - When it started - Technical details from logs - Sets appropriate priority (High, since checkout is broken) - Adds labels (bug, payment, urgent) - Suggests team/assignee ### 2. Query Issues "What high-priority bugs are currently unassigned?" Claude: - Queries Linear with filters - Returns list of issues with: - Title and ID - Status - Created date - Brief description - Ordered by priority or date ### 3. Update Issue Status "Mark LIN-1234 as in progress and assign it to me." Claude: - Finds issue LIN-1234 - Updates status to "In Progress" - Sets assignee to your Linear user - Confirms the change ### 4. Search Related Issues "Find any previous issues related to authentication timeouts." Claude: - Searches across all issues - Filters by keywords - Returns relevant historical issues - Shows if they're resolved and how ### 5. Project Reporting "Give me a status update on the Q2 Mobile Redesign project." Claude: - Queries all issues in that project - Groups by status (Todo, In Progress, Done) - Calculates completion percentage - Identifies blockers or at-risk items - Shows upcoming milestones ## Practical Workflows ### Workflow 1: Bug Report Processing **Scenario:** Bug reports come in via Slack, email, or customer support **Before integration:** 1. Read bug report 2. Open Linear 3. Create new issue 4. Copy/paste details 5. Format nicely 6. Add labels and priority 7. Assign to team 8. Link related issues 9. Post Linear link back to reporter **With integration:** Paste bug report into Claude: "Create a Linear issue for this bug report: [paste full report]" Claude: - Analyzes report - Creates well-formatted issue - Sets appropriate priority based on severity - Adds relevant labels - Suggests assignee based on expertise - Links similar historical issues - Returns Linear issue URL Copy URL back to reporter. Done. **Time saved:** 5-8 minutes per bug ### Workflow 2: Feature Request Management **Scenario:** Product team receives feature requests from customers and internal teams **Prompt:** "We've had 3 customers ask for dark mode this week. Create a feature request in Linear, check if we already have something similar, and analyze priority based on request volume." Claude: - Searches existing issues for "dark mode" - Finds related requests or creates new - Adds customer examples to description - Notes this is the 3rd request this week - Suggests priority: Medium-High (multiple requests) - Labels: feature-request, ui, customer-requested ### Workflow 3: Sprint Planning **Scenario:** Plan next sprint based on priorities and capacity **Prompt:** "Show me all high-priority issues that aren't scheduled for a sprint yet. Group by team." Claude: - Queries unscheduled high-priority issues - Groups by team (Backend, Frontend, Design, etc.) - Shows estimate totals per team - Highlights dependencies - Suggests which fit in typical sprint capacity **Follow-up:** "Add the top 5 backend issues to the current sprint." Claude: - Updates issues to current sprint - Confirms changes - Shows sprint capacity usage ### Workflow 4: Incident Management **Scenario:** Production incident requires coordination and tracking **Prompt:** "We have a production outage. Create an incident issue, link all related issues from the past week, and generate a status update template." Claude: - Creates incident issue with template: - Impact assessment - Timeline - Investigation progress - Mitigation steps - Root cause (TBD) - Prevention measures - Searches and links related issues - Sets highest priority - Adds incident label - Creates status update format for stakeholders **During incident:** "Update LIN-5678 with current status: Database replica lag resolved, monitoring for recurrence." Claude updates issue, maintaining timeline. ### Workflow 5: Retrospective Analysis **Scenario:** Analyze completed work for insights **Prompt:** "Analyze all issues completed in Q1. What were our most common bug categories? How long did features take on average? Any patterns?" Claude: - Queries Q1 completed issues - Categorizes bugs by type - Calculates cycle time metrics - Identifies patterns: - Common bug sources - Features that took longer than estimated - Team velocity trends - Blocker frequency - Generates insights for process improvement ## Advanced Workflows ### Automated Triage **Scenario:** New issues need quick categorization and routing **Prompt:** "Here are 10 new issues from user reports. Triage them: set appropriate priority, assign to correct team, and flag any that need immediate attention." Claude: - Analyzes each issue - Assesses severity and impact - Determines appropriate team based on type - Sets priority - Flags urgent items - Adds relevant labels - Provides summary of triage decisions ### Cross-Project Dependencies **Scenario:** Track dependencies across multiple projects **Prompt:** "The Mobile Redesign project depends on API updates. Show me all API-related issues that block mobile work." Claude: - Queries both projects - Identifies API issues linked to mobile features - Shows dependency chain - Highlights blockers - Suggests which API work to prioritize ### Release Planning **Scenario:** Plan what goes into next release **Prompt:** "We're planning v2.0 release. Show me all features marked for v2.0, check their status, identify what's at risk, and suggest what might need to slip to v2.1." Claude: - Queries v2.0 milestone/label - Groups by status - Analyzes completion velocity - Identifies at-risk features based on: - Remaining estimate - Dependencies not complete - Recent activity (or lack thereof) - Recommends candidates to move to v2.1 - Provides rationale for each ### Team Performance Insights **Scenario:** Understand team productivity and blockers **Prompt:** "Analyze the backend team's velocity over the last 3 sprints. Are there patterns in what's taking longer than expected? Any recurring blockers?" Claude: - Queries backend team issues across timeframe - Calculates velocity per sprint - Compares estimates to actual time - Identifies types of work that go over estimate - Flags common blockers - Suggests areas for process improvement ## Integration with Other Tools ### Linear + Notion **Use case:** Keep project documentation in sync with issue tracking "Update our Notion project status page with latest Linear progress for the API v2 project." Claude: - Queries Linear for API v2 issues - Calculates completion status - Updates Notion page with: - Current progress percentage - Issues completed this week - Upcoming milestones - Blockers or risks ### Linear + GitHub **Use case:** Create issues from pull request feedback "This PR has feedback about refactoring the auth module. Create a Linear issue to track that work." Claude: - Extracts refactoring context from PR - Creates Linear issue with: - Reference to PR and feedback - Technical details - Link to GitHub discussion - Links issue to relevant project ### Linear + Slack **Use case:** Create issues from Slack discussions In Slack thread about customer request, in Claude: "Create a Linear feature request based on this Slack discussion about CSV export functionality." Claude: - Summarizes Slack discussion - Extracts requirements - Creates formatted Linear issue - Includes link back to Slack thread - Posts Linear issue URL to Slack ## Best Practices ### 1. Use Consistent Labels and Projects Claude works better when Linear is organized: - Standard labels across teams (bug, feature, improvement) - Clear project naming conventions - Consistent priority definitions - Documented team assignments ### 2. Provide Context in Prompts Instead of: "Create an issue for the checkout bug" Use: "Create a bug report: Checkout fails for users in EU region. Error: 'Payment provider unreachable'. Affects ~500 users based on Sentry alerts." More context = better issue quality. ### 3. Review Before Critical Updates For mass updates or status changes: "Show me what would change if I move all 'Ready' issues to the current sprint" (preview) Then: "Go ahead and make those changes" (confirm) ### 4. Leverage Historical Context When creating issues: "Create a bug report for X, and include links to any similar issues we've had before." Claude searches history and connects dots. ### 5. Create Templates Define issue templates for common types: "When I create bug reports, use this format: [your template]. When I create feature requests, use this format: [template]." Claude remembers within conversation. ## Security and Permissions **API Key Scope:** Linear API keys have full workspace access: - Can create, read, update, delete issues - Can modify projects and teams - Can see all workspace data **Best practices:** - Only give API key to trusted team members - Don't share key in public channels - Rotate key periodically - Revoke immediately if compromised **Team Member Access:** Claude respects Linear permissions: - Can only see projects you have access to - Can only update issues you can edit - Can't bypass Linear's permission system ## Troubleshooting **Claude can't access Linear:** - Verify API key is correct in MCP config - Check API key hasn't been revoked - Restart Claude Code - Test API key directly via Linear API **Issues aren't updating:** - Confirm you have edit permissions - Check issue isn't locked - Verify Linear workspace status **Search isn't finding issues:** - Try different keywords - Check issue status (archived issues require explicit query) - Verify project access ## Quick Takeaway The Linear MCP server transforms issue tracking from manual data entry to intelligent automation. Setup takes 10 minutes: generate API key, install MCP server, configure Claude Code. Key workflows: bug triage, feature requests, sprint planning, incident management, and retrospective analysis. Biggest value: Turn bug reports and feedback into properly formatted, prioritized, and routed Linear issues in seconds instead of minutes. For teams using Linear as their project management system, this integration eliminates most manual issue management overhead.