Connect Claude Desktop to Linear

Use an MCP server to connect Claude Desktop to Linear for AI project management.

Introduction

30 Second Summary

Managing projects means juggling tasks, deadlines, and team updates across multiple tools. What if your AI assistant could handle all of that directly from a conversation?

In this project, you will connect Claude Desktop to Linear (a project management tool) so Claude can create tasks, track progress, and generate reports using nothing but natural language.

What You'll Build

You'll configure a local MCP server that bridges Claude Desktop and Linear, then use sample project files to demonstrate AI-powered project management.

By the end of this project, you'll have:

  • A configured Claude Desktop with a working Linear MCP integration that lets Claude read and write to your project management workspace.
  • A fully populated "Website Redesign" project in Linear with tasks, priorities, and descriptions created entirely through conversation.
  • A status report generated by Claude pulling live data from your Linear workspace.
  • Secret Mission: Use Claude to reorganize your project by priority, identify blocked tasks, and generate a sprint plan.

Are there any prerequisites?

No coding experience is required for this project. Familiarity with project management concepts like tasks, sprints, and priorities is helpful but not essential.

Set Up Your Tools

Before you can use Claude as a project management assistant, you need three tools in place.

In this step, you will install Claude Desktop, set up Node.js (the runtime that powers the connector between Claude and Linear), and create a free Linear account where your project will live.

In this step, get ready to:
  • Install and sign in to Claude Desktop.
  • Install Node.js and verify it works.
  • Create a free Linear workspace.
Download and install Claude Desktop

Claude Desktop is the app that gives you a chat interface with Claude directly on your computer. It also supports local connectors that let Claude interact with other tools on your behalf.

  • Open your web browser and go to claude.ai/download.
  • Click macOS (Mac) or Windows (Windows) to download the installer.
  • Open the downloaded file to complete the installation.

What are the system requirements?

Claude Desktop requires macOS 11 (Big Sur) or newer on Mac, or Windows 10 or newer on Windows. If your computer runs an older operating system, you will need to update it first.

  • Launch Claude Desktop from your Applications folder (Mac) or Start Menu (Windows).
  • Sign in with a free Claude account. If you do not have one, click Sign Up and create one with your email address.

You should see the Claude chat window open with an empty conversation. Claude Desktop is ready to go.

Claude Desktop not opening?

On macOS, you may see a security warning the first time you open it. Go to System Preferences then Security & Privacy and click Open Anyway.

On Windows, if the app does not appear after installing, try searching for "Claude" in the Start Menu.

Help me troubleshoot Claude Desktop not opening on my machine.

Install Node.js

Node.js is a JavaScript runtime. The connector between Claude and Linear runs as a small Node.js program on your computer, so you need Node.js installed for it to work.

  • Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Terminal (macOS) or Command Prompt (Windows) and press Enter to open it.
  • Check if Node.js is already installed by running this command:
node --version

✔️ I see version 18 or higher

If you see a version number like v24.16.0 or any number starting with 18 or above, Node.js is ready. Move on to the next substep.

ⓧ I see an older version

If the version number starts with 16 or lower, you need to upgrade.

  • Go to nodejs.org in your browser.
  • Download the LTS version (the button is labeled with a version number and "LTS").
  • Run the installer. It will replace your existing Node.js with the new version.
  • Close and reopen your Terminal or Command Prompt.
  • Run node --version again to confirm you now see v18 or higher.

Still seeing the old version?

Make sure you fully closed and reopened your terminal after installing. On macOS, if node --version still shows the old version, your system may be pointing to a previously installed copy. Try running which node to check the path.

Help me figure out why my Node.js version is not updating after I installed the latest LTS.

ⓧ Command not found

Node.js is not installed on your machine yet. Let's install it now.

  • Go to nodejs.org in your browser.
  • Click the LTS download button (the large button labeled with a version number and "LTS").
  • Run the downloaded installer and follow the prompts. Accept the defaults.
  • Close and reopen your Terminal or Command Prompt.
  • Run node --version to confirm you see v18 or higher.

Still seeing command not found?

Make sure you closed and reopened the terminal window after installing. The installer adds Node.js to your system path, but existing terminal sessions will not pick up the change until you restart them.

Help me install Node.js. I downloaded the installer from nodejs.org but the command is still not found.

Create a free Linear account

Linear is a project management tool built for software teams. You will use it as the destination for all the projects and issues that Claude creates on your behalf.

  • Open your browser and go to linear.app.
  • Click Sign up and create a free account using your email or a Google/GitHub login.
  • When prompted, create a new workspace. Name it anything you like (for example, My Projects).
  • Complete the onboarding prompts. Accept the defaults for any settings you are unsure about.

You should land on an empty workspace with no issues or projects. This blank slate is exactly what you need for the next step.

Why Linear instead of other tools?

Linear has a straightforward local connector setup that works with a single API key and one command. Other tools like Asana require complex authentication flows that can be unreliable with Claude Desktop.

Linear's free plan includes full API access and up to 250 issues, which is more than enough for this project.

Having trouble creating a workspace?

Make sure you are using a personal email. Some work email domains may redirect you to an existing company workspace.

Help me create a free Linear workspace for this project.

Your tools are ready to go. Next up, you will connect Claude Desktop to Linear so they can talk to each other.

Connect Claude Desktop to Linear

Your tools are installed and your Linear workspace is ready. Now it's time to connect them so Claude can read and write to your project management workspace directly.

Claude Desktop uses the Model Context Protocol (MCP) to communicate with external tools. By adding a configuration file to Claude Desktop, you'll tell it how to reach Linear through a local MCP server that runs on your computer.

In this step, get ready to:
  • Generate a Linear API key for Claude to authenticate with.
  • Configure Claude Desktop's MCP settings to connect to Linear.
  • Restart Claude Desktop and verify the connection works.
Generate a Linear API key

An API key is a password-like string that lets one tool prove it has permission to access another. Claude Desktop needs a Linear API key to authenticate with your workspace.

  • Switch back to Linear in your browser.
  • Click your workspace name or avatar in the top-left corner to open the menu.
  • Click Settings.
  • In the left sidebar under My Account, click API.
  • Under Personal API keys, click Create key.
  • Name your key claude-mcp and press Enter.
  • Copy the generated key immediately. It starts with lin_api_ and you will not be able to see it again after leaving this page.

What is an API key?

An API key is like a special password that one application uses to talk to another. It proves to Linear that Claude Desktop has permission to create issues, update projects, and read data in your workspace.

Keep your API key private. Anyone with this key could access your Linear workspace.

  • Paste your API key somewhere safe for now (a temporary note or your clipboard). You will need it in the next substep.

Don't see the API option?

Make sure you clicked Settings from the workspace menu (top-left), not from a project. The API section appears under My Account in the left sidebar.

help me find the API settings in Linear

Configure Claude Desktop with the Linear MCP server

Claude Desktop reads a JSON configuration file at startup to learn which MCP servers to connect to. You need to create or edit this file and add the Linear server details.

  • Open the Claude Desktop configuration file by following the instructions for your operating system:

macOS

  • In your terminal, run this command to open the config file:
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Seeing a 'does not exist' error?

If the file does not exist yet, create it first by running these two commands:

touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

The Claude folder should already exist because you opened Claude Desktop in Step 1. If you get an error about the folder not existing, make sure Claude Desktop has been opened at least once.

Windows

  • Open Command Prompt and run this command:
notepad %APPDATA%\Claude\claude_desktop_config.json

What if Notepad asks to create the file?

If Notepad displays a prompt asking whether to create a new file, click Yes. This is normal if Claude Desktop has not created the config file yet.

The file opens in a text editor. If it already has content, select all and delete it.

  • Paste the following configuration into the file, replacing lin_api_your-api-key-here with the API key you copied from Linear:
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "linear-mcp-server"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your-api-key-here"
      }
    }
  }
}

What does this configuration do?

This JSON tells Claude Desktop to start a local MCP server called linear-mcp-server using npx (which comes with Node.js). The -y flag automatically confirms the download without prompting.

The LINEAR_API_KEY environment variable passes your API key to the server so it can authenticate with your Linear workspace.

  • Save the file (Cmd+S on macOS, Ctrl+S on Windows).
  • Close the text editor.

Double check your JSON

Make sure you have replaced lin_api_your-api-key-here with your actual Linear API key. Also check that all brackets and commas are in place. A missing comma or bracket will prevent Claude from loading the config.

✔️ Awesome, I've got everything!

Great. Make sure the file is saved before moving on.

ⓧ I'd like to double check the full code

Here is the complete claude_desktop_config.json file. Make sure yours matches this structure (with your own API key in place of the placeholder):

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "linear-mcp-server"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your-api-key-here"
      }
    }
  }
}
Restart Claude Desktop and verify the connection

Claude Desktop only reads its MCP configuration at startup. Closing the window is not enough. You need to fully quit and relaunch the app.

macOS

  • Switch to Claude Desktop.
  • Press Cmd+Q to fully quit Claude Desktop.
  • Press Cmd+Space to open Spotlight, type Claude, and press Enter to relaunch it.

Windows

  • Right-click the Claude Desktop icon in the taskbar.
  • Click Exit (or Quit) to fully close the app.
  • Press the Windows key, type Claude, and press Enter to relaunch it.
  • Once Claude Desktop reopens, look at the bottom of the chat composer for the tools icon (a hammer icon).
  • Click the tools icon to see the list of available tools.
  • Confirm that Linear tools are listed. You should see tools like create_issue, search_issues, and list_teams.

What should I see?

When you click the tools icon, a panel opens showing the MCP tools that Claude can use. If Linear tools appear in the list, your connection is working. Claude can now read and write data to your Linear workspace during conversations.

Don't see the tools icon or Linear tools?

  • Make sure you fully quit Claude Desktop (not just closed the window). On macOS, check that the Claude icon is gone from the Dock. On Windows, check that it is gone from the taskbar.
  • Open the config file again and verify your JSON has no syntax errors. A missing comma, extra comma, or mismatched bracket will break the config. Try pasting your JSON into a validator like jsonlint.com to check.
  • Confirm your LINEAR_API_KEY value starts with lin_api_ and has no extra spaces around it.
  • Make sure Node.js is still installed by running node --version in your terminal. The MCP server needs Node.js to run.

help me troubleshoot why Linear tools are not showing in Claude Desktop

Your Claude-to-Linear connection is live. Next up, you'll create sample project files that Claude will use to populate your Linear workspace with a full project.

Create Your Sample Project Files

Claude is connected to Linear, but right now your Linear workspace is empty. Instead of manually clicking through Linear's UI to create a project, you'll give Claude structured documents to work from.

In this step, you'll create three sample files that represent typical project artifacts: a brief, meeting notes, and a task breakdown. These give Claude the context it needs to build out your entire project in Linear automatically.

In this step, get ready to:
  • Create a project brief with goals, timeline, and team roles.
  • Create meeting notes with action items and blockers.
  • Create a task breakdown organized by workstream.
Create the project brief

The project brief is the foundational document for your Website Redesign project. It contains the project goals, team members, deliverables, and timeline that Claude will use to create issues in Linear.

  • Switch back to your terminal and move to your Desktop by running this command:
cd ~/Desktop
  • Create a folder to hold your sample files by running:
mkdir website-redesign-files
cd website-redesign-files
  • Confirm the folder was created by running:
ls

You should see the website-redesign-files folder listed in the output (or you're already inside it after the cd command).

  • Open a text editor to create the first file. Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type TextEdit (macOS) or Notepad (Windows) and press Enter to open it.

Make it plain text on macOS

TextEdit defaults to rich text mode, which can cause issues with .md files. Before pasting anything, click Format in the menu bar and select Make Plain Text (or press Shift+Cmd+T).

  • Copy and paste the following content into your text editor:
# Website Redesign Project Brief

## Project Overview
Our company website needs a complete redesign to improve user experience, modernize the visual design, and increase conversion rates. The current site is 3 years old and no longer reflects our brand.

## Goals
- Increase homepage conversion rate by 25%
- Reduce bounce rate by 15%
- Achieve mobile-first responsive design
- Launch within 8 weeks

## Team
- Sarah (Project Lead)
- Marcus (Lead Designer)
- Priya (Frontend Developer)
- Jake (Content Strategist)
- Lisa (QA Tester)

## Key Deliverables
1. New brand style guide and design system
2. Homepage redesign with hero section and CTA optimization
3. Product pages with improved navigation
4. Mobile-responsive implementation across all pages
5. Content audit and rewrite for key landing pages
6. Performance optimization (target: <2s load time)
7. SEO migration plan to preserve rankings

## Timeline
- Weeks 1-2: Discovery and design exploration
- Weeks 3-4: Design finalization and content strategy
- Weeks 5-6: Development and content creation
- Weeks 7-8: QA testing and launch preparation

## Success Metrics
- Page load time under 2 seconds
- Mobile Lighthouse score above 90
- 25% improvement in conversion rate within 30 days of launch

What is this file for?

This brief gives Claude everything it needs to create a project in Linear: clear goals, a defined team, and specific deliverables. Claude will parse each deliverable and turn it into a trackable issue with the right priority level.

  • Save the file as project-brief.md inside the website-redesign-files folder on your Desktop.
  • On macOS, press Cmd+S. On Windows, press Ctrl+S.
  • Navigate to Desktop then website-redesign-files in the save dialog.
  • Name the file project-brief.md and click Save.

File saved as .txt instead of .md?

On Windows, Notepad may add a .txt extension automatically. In the Save dialog, change the Save as type dropdown from "Text Documents" to All Files, then type the full filename project-brief.md including the extension.

On macOS, if TextEdit saved it as .rtf, make sure you switched to plain text mode first (Format then Make Plain Text).

Help me save my file with the .md extension

✔️ Awesome, I've got everything!

Great. Make sure you've saved project-brief.md in your website-redesign-files folder on the Desktop.

ⓧ I'd like to double check the full code

Here's the full content that should be in your project-brief.md file:

# Website Redesign Project Brief

## Project Overview
Our company website needs a complete redesign to improve user experience, modernize the visual design, and increase conversion rates. The current site is 3 years old and no longer reflects our brand.

## Goals
- Increase homepage conversion rate by 25%
- Reduce bounce rate by 15%
- Achieve mobile-first responsive design
- Launch within 8 weeks

## Team
- Sarah (Project Lead)
- Marcus (Lead Designer)
- Priya (Frontend Developer)
- Jake (Content Strategist)
- Lisa (QA Tester)

## Key Deliverables
1. New brand style guide and design system
2. Homepage redesign with hero section and CTA optimization
3. Product pages with improved navigation
4. Mobile-responsive implementation across all pages
5. Content audit and rewrite for key landing pages
6. Performance optimization (target: <2s load time)
7. SEO migration plan to preserve rankings

## Timeline
- Weeks 1-2: Discovery and design exploration
- Weeks 3-4: Design finalization and content strategy
- Weeks 5-6: Development and content creation
- Weeks 7-8: QA testing and launch preparation

## Success Metrics
- Page load time under 2 seconds
- Mobile Lighthouse score above 90
- 25% improvement in conversion rate within 30 days of launch
Create the meeting notes

Meeting notes capture the team's decisions, action items, and blockers from their kickoff meeting. Claude will use these to create additional issues in Linear with priority levels based on the urgency discussed.

  • Create a new file in your text editor (Cmd+N on macOS or Ctrl+N on Windows).
  • Copy and paste the following content into the new file:
# Website Redesign - Team Kickoff Meeting
**Date:** Monday, Week 1
**Attendees:** Sarah, Marcus, Priya, Jake, Lisa

## Decisions Made
- We will use a mobile-first approach for all designs
- The new design system will be built in Figma
- Frontend will use a modern CSS framework for responsive layouts
- Content audit should start immediately — Jake to begin this week

## Action Items
- [ ] Marcus: Create 3 homepage design concepts by end of Week 1 (HIGH PRIORITY)
- [ ] Jake: Complete content audit of top 20 pages by Wednesday (HIGH PRIORITY)
- [ ] Priya: Research and recommend a CSS framework by Thursday (MEDIUM PRIORITY)
- [ ] Sarah: Set up staging environment for the new site (MEDIUM PRIORITY)
- [ ] Lisa: Write test cases for mobile responsiveness (LOW PRIORITY — needed by Week 5)

## Blockers Identified
- We don't have access to current analytics data — Sarah to request access from IT
- Brand guidelines document is outdated — Marcus will create updated version as part of design system work

## Notes
- Marcus mentioned that the current logo may need a refresh — discuss with marketing team
- Priya raised concern about legacy browser support — team agreed to drop IE11 support
- Next meeting scheduled for Thursday to review Marcus's initial concepts

What does this file do?

The action items in this file have priority tags (HIGH, MEDIUM, LOW) that Claude will interpret when creating issues. The blockers section gives Claude context to add relevant notes or labels to the issues it creates.

  • Save the file as meeting-notes.md in the same website-redesign-files folder on your Desktop.

Can't find your folder in the save dialog?

Look for Desktop in the left sidebar of the save dialog, then double-click website-redesign-files to open it. If you don't see the sidebar, click the small arrow or expand button next to the filename field to reveal the full navigation view.

Help me find my project folder in the save dialog

✔️ Awesome, I've got everything!

Great. You should now have both project-brief.md and meeting-notes.md saved in your folder.

ⓧ I'd like to double check the full code

Here's the full content that should be in your meeting-notes.md file:

# Website Redesign - Team Kickoff Meeting
**Date:** Monday, Week 1
**Attendees:** Sarah, Marcus, Priya, Jake, Lisa

## Decisions Made
- We will use a mobile-first approach for all designs
- The new design system will be built in Figma
- Frontend will use a modern CSS framework for responsive layouts
- Content audit should start immediately — Jake to begin this week

## Action Items
- [ ] Marcus: Create 3 homepage design concepts by end of Week 1 (HIGH PRIORITY)
- [ ] Jake: Complete content audit of top 20 pages by Wednesday (HIGH PRIORITY)
- [ ] Priya: Research and recommend a CSS framework by Thursday (MEDIUM PRIORITY)
- [ ] Sarah: Set up staging environment for the new site (MEDIUM PRIORITY)
- [ ] Lisa: Write test cases for mobile responsiveness (LOW PRIORITY — needed by Week 5)

## Blockers Identified
- We don't have access to current analytics data — Sarah to request access from IT
- Brand guidelines document is outdated — Marcus will create updated version as part of design system work

## Notes
- Marcus mentioned that the current logo may need a refresh — discuss with marketing team
- Priya raised concern about legacy browser support — team agreed to drop IE11 support
- Next meeting scheduled for Thursday to review Marcus's initial concepts
Create the task breakdown

The task breakdown organizes work into four workstreams with effort estimates. This gives Claude granular detail to create well-scoped issues for each team member.

  • Create another new file in your text editor (Cmd+N on macOS or Ctrl+N on Windows).
  • Copy and paste the following content into the new file:
# Website Redesign - Task Breakdown by Workstream

## Design Workstream (Marcus)
- Create mood boards and design direction (2 days)
- Design homepage concepts x3 (3 days)
- Build component library in Figma (4 days)
- Design product page template (2 days)
- Design mobile navigation patterns (1 day)
- Create icon set and illustration style (2 days)
- Final design review and handoff to dev (1 day)

## Development Workstream (Priya)
- Set up project repository and dev environment (1 day)
- Implement responsive grid system (2 days)
- Build homepage components (4 days)
- Build product page components (3 days)
- Implement navigation and routing (2 days)
- Performance optimization pass (2 days)
- Cross-browser testing fixes (2 days)

## Content Workstream (Jake)
- Audit existing content across all pages (3 days)
- Write new homepage copy and CTAs (2 days)
- Rewrite product descriptions (4 days)
- Create SEO metadata for all pages (1 day)
- Write blog migration plan (1 day)

## QA Workstream (Lisa)
- Write test plan and test cases (2 days)
- Mobile device testing matrix (1 day)
- Accessibility audit (2 days)
- Performance benchmarking (1 day)
- Final regression testing (3 days)

What does this file do?

Each workstream section maps to a team member, and each bullet is a distinct task with an effort estimate. Claude can use this structure to create individual issues and assign them to the right people in Linear.

  • Save the file as task-breakdown.md in the same website-redesign-files folder on your Desktop.
  • Confirm all three files exist by switching back to your terminal and running:
ls ~/Desktop/website-redesign-files

You should see meeting-notes.md, project-brief.md, and task-breakdown.md listed in the output.

Missing one or more files?

If a file doesn't appear, check that you saved it in the correct location. Open your website-redesign-files folder on the Desktop using Finder (macOS) or File Explorer (Windows) to see where your files actually ended up.

If a file has the wrong extension (like .txt or .rtf), rename it to use the .md extension. Right-click the file, select Rename, and change the extension manually.

Help me find or fix my sample project files

✔️ Awesome, I've got everything!

Great. All three files are ready to upload to Claude Desktop in the next step.

ⓧ I'd like to double check the full code

Here's the full content that should be in your task-breakdown.md file:

# Website Redesign - Task Breakdown by Workstream

## Design Workstream (Marcus)
- Create mood boards and design direction (2 days)
- Design homepage concepts x3 (3 days)
- Build component library in Figma (4 days)
- Design product page template (2 days)
- Design mobile navigation patterns (1 day)
- Create icon set and illustration style (2 days)
- Final design review and handoff to dev (1 day)

## Development Workstream (Priya)
- Set up project repository and dev environment (1 day)
- Implement responsive grid system (2 days)
- Build homepage components (4 days)
- Build product page components (3 days)
- Implement navigation and routing (2 days)
- Performance optimization pass (2 days)
- Cross-browser testing fixes (2 days)

## Content Workstream (Jake)
- Audit existing content across all pages (3 days)
- Write new homepage copy and CTAs (2 days)
- Rewrite product descriptions (4 days)
- Create SEO metadata for all pages (1 day)
- Write blog migration plan (1 day)

## QA Workstream (Lisa)
- Write test plan and test cases (2 days)
- Mobile device testing matrix (1 day)
- Accessibility audit (2 days)
- Performance benchmarking (1 day)
- Final regression testing (3 days)

Your sample files are ready. Next up, you'll upload these to Claude Desktop and watch it build your entire project in Linear using nothing but natural language.

Use Claude to Build Your Project in Linear

Your sample project files are ready. Now comes the exciting part: watching Claude create an entire project structure in Linear using nothing but natural language.

Instead of manually clicking through Linear's UI to create projects and issues one by one, you'll upload your documents to Claude and let it handle everything through the MCP connection. Claude reads your files, understands the content, and uses the Linear tools to create projects and issues on your behalf.

In this step, get ready to:
  • Upload your project brief and have Claude create the Website Redesign project with issues.
  • Upload your meeting notes and have Claude create action item issues with priorities.
  • Verify everything in Linear's browser interface.
Upload the project brief and create your project

Your project-brief.md file contains everything Claude needs to set up the project: goals, team roles, deliverables, and timelines. You'll upload it directly into the Claude Desktop chat and ask Claude to create the project in Linear.

  • In Claude Desktop, start a new conversation.
  • Click the + button in the lower left corner of the chat box.
  • Select Add files or photos from the menu.
  • Navigate to your Desktop, select project-brief.md, and click Open.
  • You'll see the file attached below the message input. Now type this prompt in the message box:
Read this project brief and create a new project in Linear called 'Website Redesign'. Then create issues for each major deliverable with appropriate priorities.
  • Press Enter to send the message.

What happens next?

Claude will ask for your permission before using each Linear tool. You'll see a prompt asking if Claude can use tools like create_issue or list_teams. Click Allow to let Claude proceed.

Claude will first look up your teams in Linear, then create the project, and then create individual issues for each deliverable from the brief. You'll see the tool calls happening in real time in the conversation.

  • Click Allow each time Claude asks for permission to use a Linear tool.

Once Claude finishes, you'll see a summary of what it created. It should list the Website Redesign project and 7 issues matching the key deliverables from your brief.

Allow all tools at once

If you don't want to approve each tool call individually, you can select Allow for this chat when the permission prompt appears. This lets Claude use Linear tools freely for the rest of the conversation.

Claude says it can't find Linear tools?

Make sure you fully quit and relaunched Claude Desktop after adding the config file. Closing the window is not enough. On macOS, press Cmd+Q. On Windows, right-click the taskbar icon and select Exit.

Also check that the tools icon appears in your chat composer. If it doesn't, your config file may have a syntax error.

Help me troubleshoot why Claude can't find my Linear MCP tools.

Upload meeting notes and create action items

Your meeting notes contain specific action items with assigned owners and urgency levels. Claude can parse these and turn them into properly prioritized issues.

  • In the same conversation, click the + button again.
  • Select Add files or photos and choose meeting-notes.md from your Desktop.
  • Type this prompt in the message box:
Read these meeting notes and create issues in the Website Redesign project for each action item. Set the priority based on urgency discussed in the notes.
  • Press Enter to send the message.
  • Allow the tool calls when prompted (or select Allow for this chat if you haven't already).

What does Claude do with the meeting notes?

Claude identifies the 5 action items from the meeting notes and creates a Linear issue for each one. It maps the urgency markers (HIGH, MEDIUM, LOW) from the notes to Linear's priority levels.

Each issue includes context from the meeting. For example, the content audit issue will note that Jake needs to complete it by Wednesday for the top 20 pages.

Once Claude finishes, it should confirm that it created issues for all 5 action items with priorities matching what was discussed in the meeting.

Claude created issues with wrong priorities?

Claude interprets priorities based on the context you provide. If the priorities don't match what you expected, you can follow up with a correction like: "Change the staging environment issue to Medium priority."

Help me fix the priorities on issues Claude created in Linear.

Verify your project in Linear

You've asked Claude to create a project and over a dozen issues. Now confirm everything landed correctly in Linear's interface.

  • Open your browser and go to linear.app.
  • Sign in to your workspace if prompted.
  • Click Projects in the left sidebar.
  • Click on the Website Redesign project.
  • Verify that you see issues for all 7 key deliverables from the project brief (style guide, homepage redesign, product pages, mobile-responsive implementation, content audit, performance optimization, SEO migration plan).
  • Verify that you see issues for the 5 action items from the meeting notes (homepage design concepts, content audit, CSS framework research, staging environment, test cases).
  • Click on any issue to confirm it has a description, priority level, and relevant context from your documents.

Why verify manually?

Checking Linear's UI confirms that the MCP connection works end-to-end. The data Claude created lives in Linear as real issues that any team member could pick up and work on.

This is the same result you'd get from spending 20 minutes manually creating issues one by one. Claude did it in seconds.

Don't see the project in Linear?

If your workspace has multiple teams, Claude may have created the project under a different team. Check the sidebar for other team sections.

If nothing appears at all, go back to Claude Desktop and check whether Claude reported any errors during the tool calls. A common issue is an expired or incorrect API key.

Help me find the project Claude was supposed to create in Linear.

Your project is fully set up in Linear without a single manual click in the project management UI. Next up, you'll use Claude to pull live data from this project and generate a status report.

Generate a Status Report from Live Data

In the previous step, you turned three plain markdown files into a fully populated project in Linear. Claude read your documents, extracted deliverables and action items, and created real issues with priorities and descriptions.

Now you'll see the other side of this connection. Claude can also pull live data back from Linear and update existing issues on your behalf. This turns Claude into a reporting and management tool, not just a setup assistant.

In this step, get ready to:
  • Query all issues in your Website Redesign project and get a formatted status summary.
  • Update an issue's status and add a comment through natural language.
Ask Claude for a status report

A project manager's most frequent task is checking on progress. Instead of opening Linear, filtering issues, and mentally organizing them, you can ask Claude to do all of that in one sentence.

  • Return to your Claude Desktop chat window.
  • Type the following prompt into the chat composer and press Enter:
Show me all issues in the Website Redesign project and give me a status summary organized by priority.

What happens when you send this?

Claude uses the Linear MCP tools to search your workspace for issues belonging to the Website Redesign project. It then organizes them by priority level (Urgent, High, Medium, Low) and presents a formatted summary.

Claude may ask for your permission before calling each Linear tool. Click Allow when prompted to let it proceed.

  • Review Claude's response. You should see a structured report listing your issues grouped by priority, with descriptions and current statuses.

Customize your reports

You can ask for different report formats. Try asking Claude to organize issues by team member, by workstream, or by due date. The MCP connection gives Claude full access to all issue metadata in your workspace.

Claude says it can't find the project?

Make sure you type the project name exactly as you created it. If you named it something slightly different in Step 4, use that exact name instead of "Website Redesign".

If Claude says it has no Linear tools available, click the + button at the bottom of the chat box and select Connectors to check the connection status.

help me troubleshoot why Claude can't find my Linear project

Update an issue through conversation

Reading data is useful, but the real power of this connection is that Claude can also write changes back to Linear. You can update statuses, add comments, and modify issues without ever opening the Linear interface.

  • Type the following prompt into the Claude Desktop chat composer and press Enter:
Update the issue about homepage mockups to In Progress status and add a comment saying 'Design team started work today'.

What does this demonstrate?

This prompt tests two write operations at once. Claude searches for the homepage mockups issue, changes its status to In Progress, and adds a comment. This is the same workflow a project manager would do manually, completed in a single sentence.

Claude may ask for permission before each tool call. Click Allow to let it make the changes.

  • Review Claude's confirmation. It should tell you it updated the issue status and added the comment.
  • Open Linear in your browser to verify the change.
  • Find the homepage mockups issue in your Website Redesign project. You should see its status set to In Progress and a comment reading "Design team started work today" in the activity feed.

Issue not updated in Linear?

Give it a moment and refresh your Linear browser tab. Changes usually appear within a few seconds.

If Claude says it couldn't find the issue, it may be using a slightly different name than what you see in Linear. Try rephrasing your prompt with the exact issue title as it appears in your Linear workspace.

help me figure out why Claude couldn't update my Linear issue

You now have a fully working AI-powered project management pipeline. Claude can read your project status and write updates back to Linear, all through natural conversation. Next up, the Secret Mission challenges you to take this further with sprint planning and dependency analysis.

Secret mission

Sprint Planning with Claude

You've used Claude to create issues and generate reports. But real project managers don't just track tasks. They plan sprints, identify dependencies, communicate with stakeholders, and create new work on the fly. Can you use Claude as a full sprint planning assistant?

Clean Up Your Resources

Clean Up Your Resources

This project runs entirely on free plans and local files, so there are no ongoing costs. Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

  • Linear workspace with the "Website Redesign" project and all issues.
  • Linear API key (named "claude-mcp").
  • Claude Desktop MCP configuration (claude_desktop_config.json).
  • Local sample files (project-brief.md, meeting-notes.md, task-breakdown.md).

Keep everything running

No action needed. Choose this if you're still actively experimenting with Claude and Linear together.

  • Your Linear workspace stays active on the free plan with no charges.
  • Your API key remains valid for future Claude Desktop sessions.
  • Your local sample files stay on your computer for reference.
  • Claude Desktop and Node.js remain installed for other projects.

Pause - I'll come back to this later

Revoke the API key and remove the MCP configuration to disconnect Claude from Linear. You can reconnect later by generating a new key.

  • In Linear, click your workspace name in the upper-left corner and select Settings.
  • Go to Account then Security & Access.
  • In the Personal API keys section, hover over the "claude-mcp" key and select Revoke.
  • Open your claude_desktop_config.json file and replace its contents with an empty object: {}.
  • Fully quit Claude Desktop (Cmd+Q on macOS, right-click taskbar then Exit on Windows) and reopen it.

Delete - I don't want to use this again

Remove all project resources and start fresh. Follow each step below.

Revoke the Linear API key
  • In Linear, click your workspace name in the upper-left corner and select Settings.
  • Go to Account then Security & Access.
  • In the Personal API keys section, hover over the "claude-mcp" key and select Revoke.
Delete the Linear workspace
  • In Linear, go to Settings then Workspace then General.
  • Scroll to the bottom and select the option to delete your workspace.
  • Linear will email you a confirmation code. Enter it to schedule the workspace for deletion.
  • The workspace and all data (including the "Website Redesign" project and all issues) will be permanently deleted after 48 hours. You can cancel during that window from the same settings page.

What about my Linear account?

Deleting your workspace also deletes your Linear account. If you only want to remove the project data without deleting your account, delete the individual project and issues from within Linear instead.

Reset the Claude Desktop MCP configuration
  • On macOS, open Terminal and run:
rm ~/Library/Application\ Support/Claude/claude_desktop_config.json
  • On Windows, open Command Prompt and run:
del "%APPDATA%\Claude\claude_desktop_config.json"
  • Fully quit Claude Desktop (Cmd+Q on macOS, right-click taskbar then Exit on Windows) and reopen it. Claude Desktop will recreate a blank config on next launch.
Delete the local sample files

Delete the three files you created during this project. On macOS or Linux, run:

rm ~/Desktop/project-brief.md ~/Desktop/meeting-notes.md ~/Desktop/task-breakdown.md

On Windows, run:

del "%USERPROFILE%\Desktop\project-brief.md" "%USERPROFILE%\Desktop\meeting-notes.md" "%USERPROFILE%\Desktop\task-breakdown.md"

Nice Work!

Nice Work!

You just turned Claude into your project management assistant. You now have a working Claude-to-Linear pipeline that lets you manage projects entirely through conversation.

Here's what you learned:

  • Configured Claude Desktop with a local MCP server connected to Linear using an API key.
  • Created an entire project structure in Linear using natural language and sample documents.
  • Queried live project data and generated status reports through conversation, including updating issues and adding comments without opening the Linear UI.
  • Used Claude for sprint planning, dependency analysis, and stakeholder communication.

Ready to quiz yourself?