Connecting Claude Code to Linear via MCP

What if your AI coding assistant could understand your entire project roadmap without asking? What if creating a new feature branch automatically opened a Linear issue, and closing that issue updated your git history? That’s what the Linear Model Context Protocol (MCP) server makes possible—and it changes how you think about the connection between your codebase and project management.

Linear has become the gold standard for modern software teams because it’s designed for developers. It’s fast, keyboard-driven, and unapologetically technical. But there’s been a gap: your AI coding assistant couldn’t tap into it. Until now.

This article walks you through connecting Claude Code to Linear using MCP. We’ll cover the setup, show you practical workflows, and reveal patterns you can use to build intelligent automation around your issues and branches. By the end, you’ll have a seamlessly integrated system that treats Linear and your codebase as a unified workspace.

Why Linear + Claude Code?

Before we dive into the technical setup, let’s be honest about why this matters.

Linear is information-dense. Your issues contain context: project goals, acceptance criteria, dependencies, historical decisions, even the thinking behind why you rejected an approach. Traditionally, Claude Code has no way to access this. You’d have to either:

1. Copy-paste the entire issue into the chat (tedious and breaks context)
2. Context-switch to Linear manually (kills flow)
3. Work from memory (error-prone)

With the Linear MCP integration, Claude Code can see your Linear workspace in real-time. You can ask questions like:

• “What’s in the current cycle? Let me work on the highest-priority bug.”
• “Create a branch for [issue title] and link it automatically.”
• “Show me all issues blocking this feature.”
• “Mark this issue as done and note the branch in the comment.”

This isn’t magic—it’s structural integration. Claude Code makes actual API calls to Linear, reads your issue data, and surfaces it exactly when you need it. The workflow becomes seamless because the tooling becomes invisible.

Think about the context loss that happens in normal workflows. You’re coding, spot an ambiguity in the requirements, tab over to Linear, re-read the issue, tab back to your editor. That single context switch costs you 30 seconds but drains your focus. Multiply that by 20 issues in a sprint, and you’ve lost 10 minutes plus your deep focus. The Linear MCP integration eliminates this entirely. You ask Claude directly: “What are the acceptance criteria again?” Claude fetches it from Linear in 200ms. You never leave your editor.

Setting Up the Linear MCP Server

The Linear MCP server is maintained in the mcp-servers repository alongside servers for GitHub, Notion, and others. It’s a Node.js application that exposes Linear’s REST API through the MCP protocol.

Before you start, understand what we’re building here. The MCP server acts as a translator. Your Claude Code CLI talks to the MCP server (which runs locally), and the MCP server talks to Linear’s API (which runs in the cloud). This architecture matters for security—your API key never leaves your machine, and all communication is encrypted.

Step 1: Get Your Linear API Key

First, you need credentials. Head to Linear’s workspace settings and generate a personal API key:

1. Log into Linear
2. Navigate to Settings → Account → API keys
3. Click Create new
4. Copy the key (you’ll only see it once)
5. Store it somewhere secure—we’ll use it in config

The key looks like this: lin_[randomstring]. Linear keys are scoped to your personal account, so they inherit your permission level. This means you can only query and create issues you’d normally have access to, which is a nice security boundary.

Here’s a critical point: Linear API keys are personal, not workspace-level. If you rotate your key, you need to update it everywhere it’s configured. If your teammate has the key and then leaves the company, that key needs rotation immediately. This is why we’ll see service accounts later—for team setups, you want automation keys that aren’t tied to any one person.

Step 2: Install the MCP Linear Server

If you’re using Claude Code with MCP support (available in recent versions), the setup depends on your environment. Here’s the configuration for a standard installation.

First, ensure you have Node.js installed. The Linear MCP server requires Node 16 or later. Verify with:

node --version

If Node isn’t installed, grab it from nodejs.org. The MCP ecosystem runs on Node, so it’s a baseline dependency for any MCP server.

Clone or download the MCP servers repository:

git clone https://github.com/anthropics/mcp-servers.git
cd mcp-servers/servers/linear
npm install
npm run build

This compiles the Linear server into a deployable state. The build step transpiles TypeScript to JavaScript if needed, and packages everything the server requires.

Now, create or edit your MCP configuration file. On macOS/Linux, this is typically ~/.claude/mcp.json. On Windows, it’s in your Claude Code config directory (usually %APPDATA%\Claude Code\mcp.json).

Add the Linear server configuration:

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/path/to/mcp-servers/servers/linear/dist/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_yourkeyhere"
      }
    }
  }
}

Let’s break this down:

• command: We’re using Node.js to run the MCP server
• args: Points to the installed Linear server code (the path must be absolute, not relative)
• env: The LINEAR_API_KEY is passed as an environment variable so it’s never hardcoded in config

A common mistake: using a relative path like ./mcp-servers/servers/linear/dist/index.js. The MCP server runs in the background and doesn’t know what working directory you meant. Always use absolute paths: /Users/yourname/projects/mcp-servers/servers/linear/dist/index.js.

Step 3: Verify the Connection

Restart Claude Code and check that the Linear MCP server loads correctly. Most modern versions will show MCP status in the interface. You should see “Linear” listed as an available tool.

To test the connection, open Claude Code and ask: “What MCP servers are connected?” or “List my assigned Linear issues.”

Claude Code will attempt to call the Linear tools. If the connection succeeds, you’ll get results. If it fails, you’ll get an error that tells you what went wrong.

If the connection fails, check:

• The API key is valid (try it in Linear’s API explorer first)
• The server path is correct (use ls -la /path/to/server to verify the file exists)
• Node.js is installed and on your PATH
• Your terminal has been restarted after updating PATH (PATH changes don’t apply to already-running terminals)
• The MCP configuration JSON is valid (use a JSON linter to check)
• Your firewall isn’t blocking outbound connections to api.linear.app

A pro debugging tip: test the API key directly before blaming the MCP setup. Open Linear’s API explorer (linear.app/[workspace]/api), paste this query:

query {
  me {
    displayName
    email
  }
}

And add the header: Authorization: Bearer lin_yourkey

If this works, your key is valid. If it fails, you need a new key. This isolates the problem to either the key or the MCP setup, which speeds up troubleshooting.

Once connected, Claude Code can now call Linear tools. You’re ready for the real work.

Core Linear MCP Tools

The Linear MCP server exposes a focused set of tools. You don’t get every Linear API endpoint—you get the ones that matter for development workflows.

Querying Issues and Projects

The most fundamental tool is list issues. This retrieves issues from your Linear workspace with optional filtering.

Here’s what you can query:

{
  "tool": "linear_search_issues",
  "parameters": {
    "query": "assignee:me status:In Progress",
    "limit": 20,
    "orderBy": "updatedAt"
  }
}

Expected output:

{
  "data": [
    {
      "id": "ENG-42",
      "title": "Implement OAuth2 token refresh",
      "state": "In Progress",
      "assignee": {
        "displayName": "Alice Chen",
        "email": "[email protected]"
      },
      "cycle": {
        "name": "Q1 Sprint 2"
      },
      "priority": 1,
      "dueDate": "2026-03-20",
      "description": "Add automatic token refresh to prevent expired tokens..."
    }
  ]
}

Notice the query syntax: Linear uses assignee:, status:, priority:, etc. This is powerful because it’s the same syntax you use in Linear’s web UI. If you know how to search Linear, you already know how to query it from Claude Code. There’s no special dialect to learn.

Priority deserves explanation here. Linear priorities are numeric (0-4, where 0 is lowest and 4 is urgent). When you query by priority, use numbers: priority:1 finds all P1 issues. The state values (like “In Progress,” “Backlog,” “Done”) depend on your workspace setup, but most teams follow the default Linear states.

Getting Detailed Issue Information

Sometimes you need more than a search result. The get issue tool fetches the full issue object including comments, attachments, and relationships:

{
  "tool": "linear_get_issue",
  "parameters": {
    "issueId": "ENG-42"
  }
}

Expected output:

{
  "data": {
    "id": "ENG-42",
    "title": "Implement OAuth2 token refresh",
    "description": "Add automatic token refresh to prevent expired tokens...",
    "state": "In Progress",
    "priority": 1,
    "estimate": 5,
    "createdAt": "2026-02-15T10:30:00Z",
    "updatedAt": "2026-03-15T14:22:00Z",
    "assignee": {
      "displayName": "Alice Chen",
      "email": "[email protected]"
    },
    "parent": null,
    "children": ["ENG-43", "ENG-44"],
    "relations": {
      "blocks": ["ENG-51"],
      "blockedBy": []
    },
    "comments": [
      {
        "author": "[email protected]",
        "body": "We should handle refresh token rotation too",
        "createdAt": "2026-03-14T09:15:00Z"
      }
    ],
    "attachments": [
      {
        "filename": "oauth_flow_diagram.png",
        "url": "https://linear.app/attachments/..."
      }
    ]
  }
}

This is the full picture. You get parent-child relationships, blocking relationships, comments, and even attachments. When Claude Code fetches an issue, it has context that’s usually scattered across your browser tabs.

The relations field is particularly interesting. When an issue blocks another issue, or is blocked by another, that’s captured here. This matters because you can now ask Claude: “What’s blocking me from working on this?” Claude fetches the issue, sees the blockers, and tells you which issues you need to wait on.

Attachments come through as URLs. Claude can’t download binary files, but it can see that an attachment exists and tell you where to find it. This is useful for tracking diagrams or documents mentioned in issues.

Creating Issues

You can create new issues directly from Claude Code:

{
  "tool": "linear_create_issue",
  "parameters": {
    "projectId": "ENG",
    "title": "Add dark mode toggle to settings",
    "description": "Users are requesting a dark mode option for the UI. This should persist to localStorage.",
    "priority": 2,
    "estimate": 3,
    "assigneeId": "[email protected]",
    "cycleId": "Q1_SPRINT_2"
  }
}

Expected output:

{
  "data": {
    "id": "ENG-105",
    "title": "Add dark mode toggle to settings",
    "url": "https://linear.app/company/issue/ENG-105/add-dark-mode-toggle-to-settings",
    "status": "Backlog",
    "createdAt": "2026-03-16T12:45:00Z"
  }
}

The issue is created immediately and gets an ID. Claude Code can then use this ID to link it to other resources—like a git branch.

One detail that confuses people: the cycleId is not the cycle name. When you query issues in a cycle, Linear returns human-readable names like “Q1 Sprint 2”. But when you create an issue, you need the cycle’s internal ID. You have to fetch the cycle list first (or just omit the cycle when creating—the issue goes to the backlog and you can move it later).

The assigneeId is an email address. Don’t pass a display name or user ID. Linear uses email as the universal user identifier for API operations.

Updating Issue State and Comments

Workflow tools let you move issues through your process:

{
  "tool": "linear_update_issue",
  "parameters": {
    "issueId": "ENG-42",
    "state": "Done",
    "comment": "Implemented in PR #2847. Token refresh now happens automatically before expiry."
  }
}

Expected output:

{
  "success": true,
  "data": {
    "id": "ENG-42",
    "state": "Done",
    "lastComment": {
      "body": "Implemented in PR #2847. Token refresh now happens automatically before expiry.",
      "createdAt": "2026-03-16T13:22:00Z"
    }
  }
}

This is where the integration becomes powerful. Your code work and your project management become synchronized. You don’t have to manually update issues—Claude Code does it as part of the development workflow.

Practical Workflows

Now that you understand the tools, let’s see how to use them in real development scenarios.

Workflow 1: Starting a Feature from a Linear Issue

You’re in Claude Code and you want to work on something. The Linear-aware flow looks like this:

1. Query your assigned issues in the current cycle
2. Pick one to work on
3. Create a branch that’s linked to the issue
4. Fetch the issue details to understand requirements

In practice, this is conversational:

User: “What’s in my current cycle? Let me work on something.”

Claude Code: Uses linear_search_issues with query assignee:me cycle:Current Status:Backlog

The response shows you have 5 issues in the backlog. You pick one: “Add dark mode toggle to settings” (ENG-105).

User: “Let’s work on ENG-105. Create a branch for it.”

Claude Code:

1. Fetches the full issue with linear_get_issue to get context
2. Creates a branch named eng-105-add-dark-mode-toggle
3. Updates the issue with a comment linking to the branch
4. Includes the full description and acceptance criteria in the chat context

Now you’re working with all the information you need, and Linear knows you’re working on it.

Workflow 2: Blocking Dependencies

You discover that ENG-105 depends on something else. Instead of leaving Linear to check, you ask Claude Code:

User: “Does anything block this issue?”

Claude Code fetches the issue and sees that ENG-101 blocks it. It shows you:

Issue ENG-105 is blocked by:
- ENG-101: "Update OAuth2 dependencies to latest version"
  Status: In Progress
  Assignee: Bob
  Due: 2026-03-18

You can then ask Claude Code to switch to that issue, fetch its details, or add a comment asking for an ETA. The workflow stays in Claude Code instead of bouncing to Linear. This is crucial for flow—each context switch takes 30 seconds but costs you five minutes of mental context.

Workflow 3: Batch Issue Triaging

Let’s say you want to triage all unassigned bugs. Instead of clicking through Linear’s UI:

User: “Show me all critical bugs that are unassigned.”

Claude Code calls:

{
  "query": "priority:1 status:Backlog assignee:none issue_type:Bug"
}

It gets 8 results. You then ask:

User: “Assign the first three to me and add them to the current cycle.”

Claude Code makes three linear_update_issue calls, updating each one. You can now see them in your Claude Code context and pick which one to work on first. This entire triage takes two minutes instead of ten.

Workflow 4: Closing Issues from Commits

This is where automation gets interesting. When you’re done with a feature:

User: “I’m done with ENG-105. Mark it as done and summarize what I did.”

Claude Code:

1. Creates a commit message that references the issue (fixes ENG-105)
2. Calls linear_update_issue to move it to “Done”
3. Adds a comment with a summary of the changes
4. Links to the commit hash

Linear now knows the issue is complete and has a trail back to the code that fixed it. This creates an audit trail that’s invaluable for retrospectives or debugging (“When did we ship feature X?” → Look at the closed issue).

Advanced Patterns

Issue-to-Branch Automation

One of the most powerful patterns is automatic branch creation and linking. Here’s how you’d build this:

When Claude Code creates a branch for an issue, it can:

1. Use the issue ID and title to generate a branch name (eng-105-dark-mode-toggle)
2. Update the issue with a comment: “Started work: eng-105-dark-mode-toggle“
3. Keep a local record of the link so it can reference it later

Later, when you push commits with Fixes ENG-105 in the message, Linear automatically moves the issue to “Done” (if you have this automation enabled). Claude Code can enhance this by also adding a more detailed comment with a summary of changes.

Here’s a practical example of how this orchestration works. When you ask Claude Code to “Start work on ENG-105,” the system internally:

1. Calls linear_get_issue to fetch full details
2. Extracts the issue title and cleans it for a branch name (lowercase, hyphens instead of spaces, max 50 chars)
3. Creates the branch locally
4. Calls linear_update_issue with a comment linking the branch
5. Checks out the branch and prepares your environment

The beauty is that this entire sequence happens in seconds without manual intervention. Your Linear issue now has a comment pointing to the branch. Your git history has the issue ID. They’re linked permanently.

Intelligent Issue Summarization

Claude Code can read an issue and generate concise summaries. This matters because Linear issues can get long—conversations, historical context, multiple approaches considered. When you’re context-switching, you don’t want to re-read the whole thing.

A smart pattern: when Claude Code switches you to a new issue, it:

1. Fetches the full issue with linear_get_issue
2. Extracts the core information: title, acceptance criteria, blockers, related issues
3. Summarizes recent comments (last 48 hours)
4. Identifies any external links or resources mentioned
5. Shows you exactly what changed since you last looked at it

This saves 5 minutes per issue. Across a sprint, that’s meaningful. For a team that does 50 context switches per sprint, that’s 250 minutes of reclaimed time.

Smart Notifications and Blocking Detection

Linear MCP opens the door to proactive notifications. You can ask Claude Code to:

• “Alert me if any issue I’m on gets blocked by something”
• “Show me if anyone commented on my issues in the last hour”
• “What’s changed in my current cycle since yesterday?”

These aren’t built-in Linear MCP features—they’re patterns you build by combining MCP queries with Claude’s language understanding. You write a prompt that says: “Every hour, fetch my assigned issues and their comments. Compare to what we tracked last time. Tell me what changed.”

This is beyond simple API wrapping. It’s building organizational intelligence on top of integration.

Cycle-Based Context

Linear’s cycles are powerful for time-boxing work. You can query issues by cycle:

{
  "query": "cycle:\"Q2 Sprint 1\" status:\"In Progress\""
}

Use this to:

• Show the team what you’re currently working on
• Identify work that’s at risk (in progress but approaching due date)
• Plan context switches strategically
• Understand team capacity at a glance

This is useful for standup automation—Claude Code could generate your daily standup message: “I’m working on ENG-42 and ENG-51, both on track. ENG-55 is blocked on ENG-48.”

Cross-Project Linking

Linear projects are often interconnected. ENG issues might depend on INFRA issues. Claude Code can help navigate these relationships:

{
  "query": "relatedTo:ENG-105"
}

This shows all issues in any project related to ENG-105. You get a full map of dependencies without context-switching.

Comparison to GitHub and Jira

Linear is different from both GitHub and Jira, and the MCP integration reflects those differences.

vs. GitHub: GitHub issues are tightly coupled to code (pull requests, branch protections, auto-linking). Linear is decoupled—it’s a planning tool first. This means Linear MCP focuses on issue queries and creation, not pull requests. If you’re working with a GitHub repo, you’d use the GitHub MCP server for PR operations and the Linear server for issue management. They complement each other.

vs. Jira: Jira has sprawling, customizable fields. Linear intentionally has fewer fields but keeps them universally meaningful (priority, estimate, state, cycle, assignee). The Linear MCP surface area is smaller than Jira’s because Linear itself is more opinionated. If you’re used to Jira’s flexibility, Linear’s constraints feel restrictive until you realize they’re features—they force clarity.

The key difference: Linear MCP is focused. It covers the 80% of operations you actually use repeatedly. It doesn’t try to expose everything.

Common Gotchas and How to Avoid Them

API Rate Limits

Linear allows 100 API calls per minute per API key. This is generous for normal workflows but matters if you’re batch-processing lots of issues. If you’re triaging 50 issues at once, you might hit the limit.

Solution: Cache issue data locally. If Claude Code already fetched an issue in the last 5 minutes, reuse that data instead of calling the API again. Set up a simple cache: { issueId: { data, timestamp } }. Before fetching, check if cached data is fresh.

Cycle Names vs. IDs

When creating or updating issues, you need to use the cycle ID, not the cycle name. This trips people up because the API returns readable names in query results but expects IDs for mutations.

Solution: When you first query issues in a cycle, store both the name and ID. Use the ID for updates. Better yet, ask Claude Code to fetch the cycle list first: “What cycles exist in this workspace?” Claude stores the mapping internally.

Async Updates

When Claude Code creates an issue, Linear’s system needs a moment to fully process it (integrations, automations, notifications). If Claude Code immediately tries to link it to something, the link might fail.

Solution: Add a 1-second delay between issue creation and linking. Linear is fast, but not instantaneous. For batch operations, add a 100ms delay between each update to avoid thundering the API.

Permission Boundaries

Your API key inherits your Linear permissions. If you can’t see an issue in Linear, your key can’t fetch it via API either. This is good for security but confusing when APIs fail silently.

Solution: If Claude Code says an issue doesn’t exist but you can see it in Linear, check your Linear permissions. You might not have access to that project. Your workspace admin can grant you project-level access.

Estimating Issues Without Context

Linear lets you estimate issues in story points without understanding the work. Claude Code can help here—fetch the issue details before estimating and ask Claude to suggest a point value based on the description and comments.

Solution: Build estimation into your workflow. When creating an issue, include acceptance criteria in the description. When estimating, review the criteria. A good heuristic: if you can’t explain the issue in one minute, it needs more details before estimation.

Building Your Own Tools on Top

The Linear MCP server exposes tools, but you can build higher-level abstractions on top of them.

For example, you could create a Claude Code command /linear-sprint that:

1. Fetches all issues in the current cycle
2. Groups them by status
3. Calculates total estimates
4. Shows which are at risk (in progress with 2 days until due date)
5. Recommends priority order based on blockers

This isn’t a Linear MCP feature—it’s custom orchestration on top of the core tools.

The same goes for branch-issue linking. A custom command /linear-branch ENG-105 could:

1. Fetch the issue
2. Create a branch
3. Update the issue with the branch name
4. Checkout the branch
5. Summary everything that happened

You’re composing MCP tools into higher-level workflows that match your team’s process.

Debugging and Troubleshooting

When the Linear MCP integration doesn’t work as expected, you need visibility. Here’s the debugging toolkit:

Checking MCP Server Status

Claude Code provides a status command. Run it to see which servers are connected:

# In Claude Code
/mcp status

You should see:

Connected MCP Servers:
- linear: ✓ Connected (5 tools available)
- github: ✓ Connected (12 tools available)

If Linear shows disconnected, the server process crashed. Check your error log:

tail -50 ~/.claude/linear-mcp.log

Look for:

• “Authentication failed” → API key is wrong or revoked
• “Connection refused” → Node.js server didn’t start
• “ENOENT” → File path to server is incorrect

Validating Your API Key

Before blaming Claude Code, test the API key directly using Linear’s GraphQL API explorer:

1. Go to https://linear.app/[workspace]/api
2. Paste this query:

query {
  me {
    displayName
    email
  }
}

1. Add the header: Authorization: Bearer lin_yourkey

If this works, your key is valid. If it fails, the problem is the key itself, not Claude Code.

Tracing API Calls

When something unexpected happens, you want to know what Claude Code actually requested. Add tracing to your MCP config:

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/path/to/mcp-servers/servers/linear/dist/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_yourkey",
        "DEBUG": "linear-mcp:*"
      }
    }
  }
}

Now every API call gets logged:

linear-mcp:query Calling Linear API: query { issues { nodes { id title state } } }
linear-mcp:request POST https://api.linear.app/graphql
linear-mcp:response Status 200, 142ms
linear-mcp:data Received 5 issues

This shows you exactly what Claude Code is doing.

Common Errors and Solutions

Error: “Issue not found: ENG-999”

• The issue doesn’t exist (typo in ID) OR
• Your key doesn’t have access (check project permissions)
• Solution: Verify the ID in Linear’s web UI first

Error: “Cycle not found”

• The cycle name/ID is wrong OR
• The cycle is archived OR
• You used the cycle name instead of the cycle ID

When querying, Linear returns cycles by name but requires IDs for mutations. Always use the ID for updates.

Error: “Rate limit exceeded”

You hit 100 API calls per minute. Wait a minute and retry. If this happens regularly, implement caching in Claude Code: store issue data locally for 5 minutes before re-fetching.

Error: “Assignment failed”

The assignee ID is invalid. Use email addresses, not display names: assigneeId: "[email protected]" not assigneeId: "Alice".

Configuration Best Practices

Multiple Workspaces

If you work with multiple Linear workspaces, create separate MCP server entries:

{
  "mcpServers": {
    "linear-primary": {
      "command": "node",
      "args": ["/path/to/mcp-servers/servers/linear/dist/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_primary_workspace_key"
      }
    },
    "linear-secondary": {
      "command": "node",
      "args": ["/path/to/mcp-servers/servers/linear/dist/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_secondary_workspace_key"
      }
    }
  }
}

Claude Code can then switch between them or even query both simultaneously. This matters for teams that use separate Linear workspaces for different products or departments.

Environment-Specific Keys

For team environments, store API keys in environment variables:

export LINEAR_API_KEY=$(cat ~/.linear-key)

Then reference the variable in your MCP config:

{
  "env": {
    "LINEAR_API_KEY": "$LINEAR_API_KEY"
  }
}

This keeps secrets out of config files checked into version control. Your .gitignore should always include your local MCP config:

.claude/mcp.json
~/.linear-key
.env.local

Monitoring and Logging

Add logging to your MCP server startup to verify it’s working:

LINEAR_API_KEY=lin_yourkey node /path/to/mcp-servers/servers/linear/dist/index.js 2>&1 | tee ~/.claude/linear-mcp.log

Check the log if operations fail. You’ll see which API calls were made and their responses. For persistent monitoring, consider setting up log rotation:

# macOS/Linux systemd service
[Service]
StandardOutput=journal
StandardError=journal

This ensures logs don’t fill your disk.

Security Considerations

Your Linear API key is powerful. It can:

• Read all issues your account can access
• Create new issues
• Modify existing issues
• Add comments

Treat it like a production password.

Key Rotation

Linear API keys don’t have expiration dates by default, but you can revoke them anytime. Rotate your key:

1. Every 90 days for enhanced security
2. Immediately if you suspect compromise
3. When leaving a team

When you rotate:

1. Generate a new key in Linear settings
2. Update your MCP config
3. Restart Claude Code
4. Delete the old key from Linear

Audit Trail

Linear keeps an audit log. Check it periodically:

Linear Settings → Security → Audit log

You’ll see all API calls made with your key, including who made changes and when.

Least Privilege in Teams

If you’re setting up Claude Code for a team, use a shared service account, not your personal key. Create a Linear user like “claude-code-bot” and generate its key. This way:

• You can audit changes made by the integration
• Rotating the key doesn’t affect your personal account
• The integration has no more permissions than necessary

Enterprise Deployment

For larger teams, Linear MCP integration gets more sophisticated.

Centralized Configuration Management

Instead of managing MCP config on each developer’s machine, distribute it via your configuration management system:

# Using Puppet, Ansible, or similar
copy /config/claude-mcp.json ~/.claude/mcp.json

This ensures consistency across your team.

Integration with CI/CD

You can call Linear MCP from CI pipelines. When a deployment succeeds:

# In your CI/CD script
curl -X POST https://automateanddeploy.com:3000/linear \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update_issue",
    "issueId": "ENG-42",
    "state": "Done",
    "comment": "Deployed to production in build #1234"
  }'

This closes issues automatically when code ships.

Compliance and Data Governance

If your company has data governance requirements:

1. Linear MCP only touches Linear—it doesn’t export data
2. API keys can be revoked immediately
3. All API calls are audited by Linear
4. Use service accounts, not personal keys, for automation

Document your MCP setup in your data governance policy. Show that it uses authenticated APIs with audit trails.

The Future of Linear + Claude Code

The Linear MCP integration is still early, but the trajectory is clear. Future improvements might include:

• Real-time webhooks: Linear could push notifications to Claude Code when issues are updated by teammates
• Smart triage: Claude Code could analyze issue descriptions and suggest priority, estimate, and assignee
• Cycle analytics: Automated sprint retrospectives based on what was completed vs. estimated
• Cross-tool consistency: Syncing linear issues with git commits and pull requests seamlessly

For now, the foundation is solid. You have query, create, and update. That covers the majority of developer workflows.

Wrapping Up

Connecting Claude Code to Linear via MCP bridges a gap that shouldn’t have existed in the first place. Your project management system and your coding assistant can now see and influence each other.

The setup is straightforward: get an API key, add it to MCP config, restart Claude Code. The tools are focused: search, fetch, create, update. The workflows are natural: ask Claude Code what you’re working on, get context, make changes, mark it done.

What changes is your mental overhead. You stay in Claude Code longer. You context-switch less. Your issues and branches remain synchronized because the tooling makes it automatic. That’s the real value—not flashy automation, just better continuity.

Start with a simple query: “Show me what I’m assigned to.” Explore the issue details. Create a branch. Mark it done. Build from there. The integration surfaces naturally once the connection exists.

Your roadmap and your code are no longer separate documents. They’re a unified workspace.

---

-iNet