linear-mcp
The Linear MCP Server is designed to interface with Linear's API, allowing users to manage issues, projects, and teams through comprehensive tools and operations. It supports authentication via API Key and includes features like bulk issue management, while also working on advanced functionalities such as OAuth flow and complex search filters.
Linear MCP Server
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.
Setup Guide
1. Environment Setup
- Clone the repository
- Install dependencies:
npm install
- Copy
.env.example
to.env
:cp .env.example .env
2. Authentication
The server supports two authentication methods:
API Key (Recommended)
- Go to Linear Settings
- Navigate to the "Security & access" section
- Find the "Personal API keys" section
- Click "New API key"
- Give the key a descriptive label (e.g. "Cline MCP")
- Copy the generated token immediately
- Add the token to your
.env
file:LINEAR_API_KEY=your_api_key
OAuth Flow (Alternative) NOT IMPLEMENTED
- Create an OAuth application at https://linear.app/settings/api/applications
- 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
- Build the server:
npm run build
- Start the server:
npm start
4. Cline Integration
-
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
- macOS:
-
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": [] } } }
Available Actions
The server currently supports the following operations:
Issue Management
- ✅ Create issues with full field support (title, description, team, project, etc.)
- ✅ Update existing issues (priority, description, etc.)
- ✅ Delete issues (single or bulk deletion)
- ✅ Search issues with filtering
- ✅ Associate issues with projects
- ✅ Create parent/child issue relationships
Project Management
- ✅ Create projects with associated issues
- ✅ Get project information
- ✅ Associate issues with projects
Team Management
- ✅ Get team information (with states and workflow details)
- ✅ Access team states and labels
Authentication
- ✅ API Key authentication
- ✅ Secure token storage
Batch Operations
- ✅ Bulk issue creation
- ✅ Bulk issue deletion
Bulk Updates (In Testing)
- 🚧 Bulk issue updates (parallel processing implemented, needs testing)
Features in Development
The following features are currently being worked on:
Issue Management
- 🚧 Comment functionality (add/edit comments, threading)
- 🚧 Complex search filters
- 🚧 Pagination support for large result sets
Metadata Operations
- 🚧 Label management (create/update/assign)
- 🚧 Cycle/milestone management
Project Management
- 🚧 Project template support
- 🚧 Advanced project operations
Authentication
- 🚧 OAuth flow with automatic token refresh
Performance & Security
- 🚧 Rate limiting
- 🚧 Detailed logging
- 🚧 Load testing and optimization
Development
# Install dependencies
npm install
# Run tests
npm test
# Run integration tests (requires LINEAR_API_KEY)
npm run test:integration
# Build the server
npm run build
# Start the server
npm start
Integration Testing
Integration tests verify that authentication and API calls work correctly:
- Set up authentication (API Key recommended for testing)
- Run integration tests:
npm run test:integration
For OAuth testing:
- Configure OAuth credentials in
.env
- Remove
.skip
from OAuth tests insrc/__tests__/auth.integration.test.ts
- Run integration tests