Skip to content
Back to search

linear-mcp

a private MCP server for accessing Linear

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cline--linear-mcp/badge.svg)](/listings/cline--linear-mcp)

HTML

<a href="/listings/cline--linear-mcp"><img src="/api/listings/cline--linear-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Environment Setup

1. Clone the repository 2. Install dependencies:

   npm install

3. Copy `.env.example` to `.env`:

   cp .env.example .env

2. Authentication

The server supports two authentication methods:

API Key (Recommended)

1. Go to Linear Settings 2. Navigate to the "Security & access" section 3. Find the "Personal API keys" section 4. Click "New API key" 5. Give the key a descriptive label (e.g. "Cline MCP") 6. Copy the generated token immediately 7. Add the token to your `.env` file:

   LINEAR_API_KEY=your_api_key

OAuth Flow (Alternative) ***NOT IMPLEMENTED***

1. Create an OAuth application at https://linear.app/settings/api/applications 2. Configure OAuth environment variables in `.env`:

   LINEAR_CLIENT_ID=your_oauth_client_id
   LINEAR_CLIENT_SECRET=your_oauth_client_secret
   LINEAR_REDIRECT_URI=http://localhost:3000/callback

3. Running the Server

1. Build the server:

   npm run build

2. Start the server:

   npm start

4. Cline Integration

1. Open your Cline MCP settings file: - macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - Windows: `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` - Linux: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

2. Add the Linear MCP server configuration:

   {
     "mcpServers": {
       "linear": {
         "command": "node",
         "args": ["/path/to/linear-mcp/build/index.js"],
         "env": {
           "LINEAR_API_KEY": "your_personal_access_token"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 210 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Linear MCP Server
  2. An MCP server for interacting with Linear's API. This server provides a set of tools for managing Linear issues, projects, and teams through Cline.
  3. ## Setup Guide
  4. ### 1. Environment Setup
  5. 1. Clone the repository
  6. 2. Install dependencies:
  7. ```bash
  8. npm install
  9. ```
  10. 3. Copy `.env.example` to `.env`:
  11. ```bash
  12. cp .env.example .env
  13. ```
  14. ### 2. Authentication
  15. The server supports two authentication methods:
  16. #### API Key (Recommended)
  17. 1. Go to Linear Settings
  18. 2. Navigate to the "Security & access" section
  19. 3. Find the "Personal API keys" section
  20. 4. Click "New API key"
  21. 5. Give the key a descriptive label (e.g. "Cline MCP")
  22. 6. Copy the generated token immediately
  23. 7. Add the token to your `.env` file:
  24. ```
  25. LINEAR_API_KEY=your_api_key
  26. ```
  27. #### OAuth Flow (Alternative) ***NOT IMPLEMENTED***
  28. 1. Create an OAuth application at https://linear.app/settings/api/applications
  29. 2. Configure OAuth environment variables in `.env`:
  30. ```
  31. LINEAR_CLIENT_ID=your_oauth_client_id
  32. LINEAR_CLIENT_SECRET=your_oauth_client_secret
  33. LINEAR_REDIRECT_URI=http://localhost:3000/callback
  34. ```
  35. ### 3. Running the Server
  36. 1. Build the server:
  37. ```bash
  38. npm run build
  39. ```
  40. 2. Start the server:
  41. ```bash
  42. npm start
  43. ```
  44. ### 4. Cline Integration
  45. 1. Open your Cline MCP settings file:
  46. - macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  47. - Windows: `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  48. - Linux: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  49. 2. Add the Linear MCP server configuration:
  50. ```json
  51. {
  52. "mcpServers": {
  53. "linear": {
  54. "command": "node",
  55. "args": ["/path/to/linear-mcp/build/index.js"],
  56. "env": {
  57. "LINEAR_API_KEY": "your_personal_access_token"
  58. },
  59. "disabled": false,
  60. "autoApprove": []
  61. }
  62. }
  63. }
  64. ```
  65. ## Available Actions
  66. The server currently supports the following operations:
  67. ### Issue Management
  68. - ✅ Create issues with full field support (title, description, team, project, etc.)
  69. - ✅ Update existing issues (priority, description, etc.)
  70. - ✅ Delete issues (single or bulk deletion)
  71. - ✅ Search issues with filtering
  72. - ✅ Associate issues with projects
  73. - ✅ Create parent/child issue relationships
  74. - ✅ Read and create comments and threaded comments
  75. ### Project Management
  76. - ✅ Create projects with associated issues
  77. - ✅ Get project information **with rich text descriptions**
  78. - ✅ Search projects **with rich text descriptions**
  79. - ✅ Associate issues with projects
  80. - ✅ Proper description handling using Linear's `documentContent` field
  81. ### Team Management
  82. - ✅ Get team information (with states and workflow details)
  83. - ✅ Access team states and labels
  84. ### Authentication
  85. - ✅ API Key authentication
  86. - ✅ Secure token storage
  87. ### Batch Operations
  88. - ✅ Bulk issue creation
  89. - ✅ Bulk issue deletion
  90. ### Bulk Updates (In Testing)
  91. - 🚧 Bulk issue updates (parallel processing implemented, needs testing)
  92. ## Rich Text Description Support
  93. The server now properly handles Linear's rich text descriptions for projects:
  94. - **Legacy Support**: Maintains compatibility with the old `description` field
  95. - **Rich Content**: Uses Linear's `documentContent` field for actual description content
  96. - **Automatic Fallback**: Falls back to legacy field if rich content is unavailable
  97. - **Type Safety**: Includes proper TypeScript types for both description formats
  98. ### How It Works
  99. Linear uses a dual-field system for descriptions:
  100. 1. `description` - Legacy field (often empty for backward compatibility)
  101. 2. `documentContent.content` - Contains the actual rich text description content
  102. The MCP server automatically:
  103. - Queries both fields from Linear's API
  104. - Prioritizes `documentContent.content` over the legacy `description` field
  105. - Provides a utility function `getProjectDescription()` for consistent access
  106. - Returns an `actualDescription` field in responses for easy access
  107. ## Features in Development
  108. The following features are currently being worked on:
  109. ### Issue Management
  110. - 🚧 Complex search filters
  111. - 🚧 Pagination support for large result sets
  112. ### Metadata Operations
  113. - 🚧 Label management (create/update/assign)
  114. - 🚧 Cycle/milestone management
  115. ### Project Management
  116. - 🚧 Project template support
  117. - 🚧 Advanced project operations
  118. ### Authentication
  119. - 🚧 OAuth flow with automatic token refresh
  120. ### Performance & Security
  121. - 🚧 Rate limiting
  122. - 🚧 Detailed logging
  123. - 🚧 Load testing and optimization
  124. ## Development
  125. ```bash
  126. # Install dependencies
  127. npm install
  128. # Run tests
  129. npm test
  130. # Run integration tests (requires LINEAR_API_KEY)
  131. npm run test:integration
  132. # Build the server
  133. npm run build
  134. # Start the server
  135. npm start
  136. ```
  137. ## Integration Testing
  138. Integration tests verify that authentication and API calls work correctly:
  139. 1. Set up authentication (API Key recommended for testing)
  140. 2. Run integration tests:
  141. ```bash
  142. npm run test:integration
  143. ```
  144. For OAuth testing:
  145. 1. Configure OAuth credentials in `.env`
  146. 2. Remove `.skip` from OAuth tests in `src/__tests__/auth.integration.test.ts`
  147. 3. Run integration tests
  148. ## Recent Improvements
  149. ### Project Description Support (Latest)
  150. - ✅ Fixed empty project descriptions by implementing Linear's `documentContent` field support
  151. - ✅ Added proper TypeScript types for rich text content
  152. - ✅ Implemented automatic fallback from rich content to legacy description
  153. - ✅ Updated all project-related queries and handlers
  154. - ✅ Added comprehensive tests for new description handling
  155. - ✅ Maintained backward compatibility with existing API consumers
  156. ### Previous Improvements
  157. - ✅ Enhanced type safety across all operations
  158. - ✅ Implemented true batch operations for better performance
  159. - ✅ Improved error handling and validation
  160. - ✅ Added comprehensive test coverage
  161. - ✅ Refactored architecture for better maintainability

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.