Linear MCP Server

A Model Context Protocol (MCP) server for Linear - fetch your assigned issues as markdown

Features

• 📋 Get your assigned issues - Fetch all issues assigned to you in Linear
• 🔍 Filter by status - Filter issues by status (Todo, In Progress, Done, etc.)
• 🏷️ Filter by team - Filter issues by team name
• 🔎 Get specific issue - Fetch a specific issue by ID
• 📝 Markdown output - All issues returned as formatted markdown
• 📄 Export to file - Export issues to markdown for AI agents to track
• 🎯 Priority sorting - Issues automatically sorted by priority
• ✅ Full MCP compliance - Properly implements the MCP protocol

Installation

Prerequisites

• Node.js >= 18.0.0
• A Linear account with an API key

Get Linear API Key

1. Go to Linear Settings > API
2. Click "Create personal API key"
3. Give it a name (e.g., "MCP Server")
4. Copy the key (starts with lin_api_)

Install Dependencies

cd linear-mcp
npm install

Build

npm run build

Setup

For Claude Code

Add this to your Claude config (usually at ~/.config/claude-code/mcp_config.json):

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

Replace /path/to/linear-mcp/dist/index.js with the actual absolute path.

For Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "linear-mcp": {
      "enabled": true,
      "command": "node",
      "args": ["/path/to/linear-mcp/dist/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your-key-here"
      }
    }
  }
}

For Continue.dev

Add to ~/.continue/config.json:

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

For Cline (VS Code)

Add to your Cline settings:

{
  "mcpServers": [
    {
      "name": "linear",
      "command": "node",
      "args": ["/path/to/linear-mcp/dist/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your-key-here"
      }
    }
  ]
}

Testing

Test API Connection

LINEAR_API_KEY=lin_api_your-key npm run test

Test MCP Protocol

LINEAR_API_KEY=lin_api_your-key npm run test:mcp

This verifies the server correctly implements the MCP protocol by sending actual JSON-RPC messages.

Usage

Once configured, you can ask your AI assistant to:

• "Show me my Linear issues"
• "What issues do I have in progress?"
• "Get my issues for the x team"
• "Show me issue XYZ-123"

Available Tools

get-my-issues

Get all issues assigned to you.

Parameters:

• status (optional): Filter by status - "Backlog", "Todo", "In Progress", "Done", or "Canceled"
• team (optional): Filter by team name

Example:

{
  "name": "get-my-issues",
  "arguments": {
    "status": "In Progress",
    "team": "Alphonse"
  }
}

get-issue-by-id

Get a specific issue by its ID.

Parameters:

• issueId (required): The Linear issue ID (e.g., "LIN-123")

Example:

{
  "name": "get-issue-by-id",
  "arguments": {
    "issueId": "LIN-123"
  }
}

export-issues

Export issues to a markdown file with AI agent todo lists for tracking progress. Issues are sorted by priority (highest first).

Parameters:

• outputFile (required): Path to the output markdown file
• status (optional): Filter by status - "Backlog", "Todo", "In Progress", "Done", or "Canceled"
• team (optional): Filter by team name
• limit (optional): Maximum number of issues to export (takes top N by priority)

Examples:

{
  "name": "export-issues",
  "arguments": {
    "outputFile": "./issues.md",
    "team": "Alphonse",
    "status": "Todo"
  }
}

{
  "name": "export-issues",
  "arguments": {
    "outputFile": "./top-3-todo.md",
    "status": "Todo",
    "limit": 3
  }
}

Usage with AI agent:

• "Export my Alphonse Todo issues to alphonse-todo.md"
• "Take the first 3 issues by priority into a todo file"
• "Create a todo with my top 5 high-priority issues"

{
  "name": "export-issues",
  "arguments": {
    "outputFile": "./issues.md",
    "team": "Alphonse",
    "status": "Todo"
  }
}

This creates a markdown file with:

• Summary table with issue counts
• Overall progress tracker
• Each issue with AI agent todo checklist
• Sorted by priority

Usage with AI agent:

"Export my Alphonse Todo issues to ./alphonse-todo.md"
"Create a file with all my issues"

Exporting Issues to a File

You can export your Linear issues to a markdown file that AI agents can use to track progress. This is useful for:

• Giving an AI agent a todo list of issues to work through
• Creating a snapshot of your current workload
• Generating reports or documentation
• Batch processing issues with AI

Option 1: Use MCP Tool (Recommended)

Ask your AI assistant to export issues:

"Export my Alphonse team issues to alphonse-issues.md"
"Export all Todo issues to ./todo.md"

The AI agent will use the export-issues MCP tool directly.

Option 2: CLI Tool

You can also run the export directly from the command line:

# Export all issues
LINEAR_API_KEY=lin_api_your-key npm run export -- my-issues.md

# Filter by team
LINEAR_API_KEY=lin_api_your-key npm run export -- alphonse-issues.md --team Alphonse

# Filter by status
LINEAR_API_KEY=lin_api_your-key npm run export -- todo-issues.md --status "Todo"

# Combine filters
LINEAR_API_KEY=lin_api_your-key npm run export -- alphonse-todo.md --team Alphonse --status "Todo"

Exported File Format

Sort by status

npm run export -- issues.md --status

Sort by issue identifier

npm run export -- issues.md --identifier

### Exported File Format

The exported markdown file includes:

- Summary table with issue counts by status
- Overall progress tracker with checkboxes
- Each issue with:
  - Status and priority indicators (emojis)
  - Issue description
  - Direct link to Linear
  - AI Agent Todo checklist for tracking progress

Example output:

```markdown
# Linear Issues Export

**Generated:** 2025-02-02T12:00:00.000Z
**Total Issues:** 15
**Team:** Alphonse

## Summary

| Status | Count |
|--------|-------|
| Total | 15 |
| Todo | 8 |
| In Progress | 3 |
| Done | 4 |

## Issues

### 1. [ALP-76] Update footer social icons

📝 **Status:** Todo
🟠 **Priority:** High
**URL:** https://linear.app/...

**Description:** Update the footer...

#### AI Agent Todo

- [ ] **Review Issue:** Read and understand the requirements
- [ ] **Research:** Look up relevant documentation/examples
- [ ] **Implement:** Make the necessary code changes
- [ ] **Test:** Verify the implementation works
- [ ] **Update Status:** Mark as complete in Linear when done

---

Using with AI Agents

Once exported, you can share the file with an AI agent:

# With Claude Code
claude "Please work through the issues in alphonse-issues.md"

# Or include in your project
cp alphonse-issues.md ./path/to/project/

The AI agent can then:

1. Read through the issues
2. Check off items as it completes them
3. Update the file with progress notes
4. Reference the direct links to Linear for more details

Example Output

# My Linear Issues

## LIN-42: Fix authentication bug

**Status:** In Progress
**Priority:** Urgent
**URL:** https://linear.app/team/issue/LIN-42
**Assignee:** John Doe (john@example.com)
**Project:** Q1 Sprint
**Team:** Backend

### Description
Users are unable to log in when using SSO.

**Labels:** bug, urgent, authentication

---

## LIN-41: Update documentation

**Status:** Todo
**Priority:** Low
**URL:** https://linear.app/team/issue/LIN-41

### Description
Add API documentation for new endpoints.

---

Development

Project Structure

linear-mcp/
├── src/
│   ├── index.ts      # MCP server entry point
│   ├── linear.ts     # Linear API client
│   ├── format.ts     # Markdown formatting
│   ├── types.ts      # TypeScript types
│   ├── test.ts       # API connection test
│   └── test-mcp.ts   # MCP protocol test
├── dist/             # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Scripts

• npm run build - Compile TypeScript
• npm run dev - Build and run the server
• npm run test - Test API connection
• npm run test:mcp - Test MCP protocol

Troubleshooting

"LINEAR_API_KEY environment variable is required"

Make sure you've set the LINEAR_API_KEY in your MCP config's env section.

"Linear API error: 401"

Your API key is invalid. Check that you copied it correctly from Linear settings.

No issues returned

• Make sure you have issues assigned to you in Linear
• Check that your API key has the right permissions
• Try running npm run test to debug

MCP server not found

• Make sure you've built the project with npm run build
• Check the path in your MCP config is correct (use absolute path)
• Restart your AI editor/IDE

Security

API Key Handling

• Never commit API keys to version control - use environment variables
• The .gitignore file excludes .env files
• API keys are only stored in memory during runtime
• Error messages are sanitized to prevent leakage of sensitive information

Environment Variable Isolation

The test suite (test-mcp.ts) only passes necessary environment variables to child processes:

• PATH - For executable lookup
• HOME - For user directory access
• LINEAR_API_KEY - For Linear authentication

This prevents accidental leakage of other environment variables.

Error Message Sanitization

• API error messages only include HTTP status codes, not full response bodies
• GraphQL errors only include error messages, not stack traces or internal details
• Error objects are never logged directly - only error messages

Recommendations

1. Rotate API keys regularly - Generate new keys periodically in Linear
2. Use separate keys - Create different keys for different environments
3. Monitor usage - Check Linear's API usage dashboard for suspicious activity
4. Principle of least privilege - Only grant necessary permissions to API keys

Reporting Security Issues

If you discover a security vulnerability, please email it to the repository owner privately before creating a public issue.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Acknowledgments

• Built with Model Context Protocol SDK
• Uses Linear GraphQL API

Made with ❤️ for the Linear community