Claude + Linear Integration: Project Management Guide
Claude's Linear integration automates issue tracking and project management. MCP server setup enables intelligent workflows for engineering and ops teams.
In this article
{"type":"component","component":"AffiliateDisclosure","props":{"variant":"default"}}
{"type":"component","component":"ToolResourceBox","props":{"tools":[{"programId":"linear","name":"Linear","description":"Modern issue tracking for software teams"}]}}
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:
- 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
Step 2: Install Linear MCP Server
<code class="language-bash">npm install -g @anthropic-ai/mcp-linear</code>
Step 3: Configure Claude Code
Add to ~/.config/claude/mcp.json (macOS/Linux) or %APPDATA%\Claude\mcp.json (Windows):
<code class="language-json">{
<p>"mcpServers": { "linear": { "command": "mcp-linear", "env": { "LINEAR_API_KEY": "your_api_key_here" } } } }</code>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:
- 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?"
Read the original source on github.com
Claude:
- Queries Linear with filters
- Returns list of issues with:
- 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 API Reference: Official API documentation for Claude integration Learn more
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."
Model Context Protocol: Official MCP documentation and server registry Learn more
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
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.
Workflow 2: Feature Request Management
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
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
Claude:
- Updates issues to current sprint
- Confirms changes
- Shows sprint capacity usage
Workflow 4: Incident Management
Claude:
- Creates incident issue with template:
- 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
Claude updates issue, maintaining timeline.
Workflow 5: Retrospective Analysis
Claude:
- Queries Q1 completed issues
- Categorizes bugs by type
- Calculates cycle time metrics
- Identifies patterns:
- Features that took longer than estimated - Team velocity trends - Blocker frequency
- Generates insights for process improvement
Advanced Workflows
Automated Triage
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
Claude:
- Queries both projects
- Identifies API issues linked to mobile features
- Shows dependency chain
- Highlights blockers
- Suggests which API work to prioritize
Release Planning
Claude:
- Queries v2.0 milestone/label
- Groups by status
- Analyzes completion velocity
- Identifies at-risk features based on:
- Dependencies not complete - Recent activity (or lack thereof)
- Recommends candidates to move to v2.1
- Provides rationale for each
Team Performance Insights
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
"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:
- Issues completed this week - Upcoming milestones - Blockers or risks
Linear + GitHub
"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:
- Technical details - Link to GitHub discussion
- Links issue to relevant project
Linear + Slack
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
Linear API keys have full workspace access:
- Can create, read, update, delete issues
- Can modify projects and teams
- Can see all workspace data
- Only give API key to trusted team members
- Don't share key in public channels
- Rotate key periodically
- Revoke immediately if compromised
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
- 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
- Confirm you have edit permissions
- Check issue isn't locked
- Verify Linear workspace status
- 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.
Get the Claude playbook in your inbox.
One weekly email for Claude and Claude Code users. Real workflows, no hype. Subscribe and we send you The Claude Power-User Cheatsheet.
— ¶ —
Luke Thompson
Luke Thompson is the founder of The Operations Guide, LLC and editor of The Claude Insider. Based in Jonesborough, Tennessee, he has spent years building AI-augmented business systems and automation workflows for operators and teams. He began working with large language models in production well before the current wave of consumer AI tools, integrating them into client workflows, content pipelines, and operational infrastructure. At The Claude Insider, he writes about Claude with the specificity of someone who uses it daily as a professional tool — not as a reviewer or commentator, but as a builder. His coverage focuses on what actually works: prompt patterns, API integration strategies, agentic workflows, and the real-world tradeoffs that practitioners face. He is not affiliated with Anthropic, PBC.
Articles are researched and drafted with AI assistance, reviewed and edited by Luke Thompson.
Know where AI can pay off in your company.
Take the free two-minute AI Readiness Assessment. See your score, the two gaps holding you back, and the next move worth making.
