Manage Linear Projects Using Claude Code

Let's Work with an MCP Server: Linear

Linear is where many teams track issues, projects, and sprints. Instead of opening Linear every time you need to create or check issues, let's connect Claude Code directly.

We'll use an MCP server — a small program that lets Claude talk to Linear's API.

What you'll be able to do

After setup, Claude can:

• List your issues and projects
• Create new issues with full details
• Update issue status and assignees
• Search across your Linear workspace
• Add comments to existing issues

Understanding MCP servers

MCP (Model Context Protocol) servers are programs that translate between Claude and external services. The flow:

1. You ask Claude: "Create an issue for the login bug"
2. Claude tells the MCP server what it needs
3. The MCP server calls Linear's API
4. Linear creates the issue
5. The MCP server tells Claude the result
6. Claude confirms: "Created issue FE-123"

You don't see steps 2-5 — Claude just does the thing.

Step 1: Get a Linear API key

You need a Linear API key so the MCP server can access your workspace:

1. Open Linear
2. Go to Settings → API → Personal API keys
3. Click "Create key"
4. Give it a name like "Claude Code MCP"
5. Copy the key somewhere safe

Step 2: Install the Linear MCP server

The Linear MCP server is installed via npm (Node.js package manager):

npm install -g @anthropic/mcp-server-linear

Don't have npm? Install Node.js first: https://nodejs.org — the "LTS" version is fine.

Step 3: Configure Claude Code

Claude Code needs to know about the MCP server. Add it to your configuration.

Create or edit ~/.claude/config.json:

{
  "mcp_servers": [
    {
      "name": "linear",
      "command": "npx",
      "args": ["@anthropic/mcp-server-linear"],
      "env": {
        "LINEAR_API_KEY": "your-api-key-here"
      }
    }
  ]
}

Replace your-api-key-here with the API key you created.

Step 4: Test the connection

Start a new Claude Code session:

claude

Ask Claude to check the connection:

List my Linear issues from the current sprint.

If configured correctly, Claude lists your issues. If something's wrong, it'll tell you what error occurred.

Common operations

List issues:

Show me all open issues assigned to me in Linear.

Create an issue:

Create a Linear issue:
- Title: "Mobile app crashes on login"
- Description: "Users report the app crashes when tapping the login button on iOS 17"
- Team: Engineering
- Priority: High
- Labels: bug, mobile

Update an issue:

Move issue FE-234 to "In Progress" and assign it to me.

Search issues:

Find all issues related to "authentication" that were created this month.

Add a comment:

Add a comment to FE-234: "Investigated this — root cause is a null pointer in the auth handler. PR coming tomorrow."

Combining with other workflows

The real value is integration with other tasks:

From meeting notes to issues:

Read the meeting notes from standup.md.
For each action item mentioned, create a Linear issue in the Engineering team.
Set priority based on the urgency mentioned in the notes.

From bug reports to issues:

Read bug_reports.csv.
For each row, create a Linear issue with:
- Title: The "summary" column
- Description: The "details" column
- Priority: Based on the "severity" column (critical=urgent, high=high, medium=normal, low=low)

Status report from Linear:

Get all issues completed this week from Linear.
Generate a markdown summary grouped by team member.
Include issue titles and any notable comments.
Save as weekly_accomplishments.md

Workflow example: Sprint planning

Here's a complete workflow:

I'm planning the next sprint. Help me:

1. Get all issues in the backlog from Linear, sorted by priority
2. Read capacity.csv which shows each team member's availability
3. Based on issue estimates and capacity:
   - Recommend which issues to include in the sprint
   - Flag if we're over-committed
4. Create a sprint_plan.md summary
5. For issues we're committing to, update their status in Linear to "Sprint Ready"

Linear data + local data + Claude analysis + Linear updates = complete planning workflow.

Setting up project-specific context

Add Linear context to your CLAUDE.md:

# Engineering Sprint Project

## Linear Context
- Main team: "Engineering"
- Current sprint: "Sprint 23"
- Default labels: bug, feature, tech-debt, documentation

## My workflow
- Bugs go in with label "bug" and high priority
- Features go in with label "feature" and normal priority  
- Assign to me unless specified otherwise
- Use Linear's standard workflow: Backlog → Sprint Ready → In Progress → In Review → Done

Now Claude knows your defaults without you repeating them.

Security note

Your Linear API key gives Claude full access to your Linear workspace — reading, creating, editing, and deleting issues. Be thoughtful:

• Review issue creation before Claude creates them
• Don't give Claude delete permissions if you're nervous (use a restricted API key)
• Test with a sandbox project first

Troubleshooting

"Not authenticated":

• Check your API key in the config
• Verify the key works by testing with curl

"Team not found":

• Use the exact team name from Linear
• Check case sensitivity

"Permission denied":

• Your API key might not have access to that team/project
• Check Linear's key permissions

What you've unlocked

Linear is now part of your Claude Code toolkit:

• Create issues from any data source
• Track progress without leaving the terminal
• Build workflows that span multiple tools

Next up: connecting to everything else with Zapier MCP.