Content
# Linear MCP Server
## Overview
This project implements a Model Context Protocol (MCP) server that acts as a bridge between Claude and the Linear task/issue management system. It allows Claude to interact with Linear through the following tools:
1. **get_ticket** - Retrieve detailed information about a specific Linear ticket
2. **get_my_issues** - List issues assigned to the current user with filtering by state
3. **add_comment** - Add comments to Linear tickets
4. **create_issue** - Create a new issue in Linear
5. **get_teams** - Retrieve available teams for reference
## Installation
No direct installation is needed. The package will be automatically downloaded and used by your Claude integration when configured properly.
## Usage
1. Obtain a Linear API key from your [Linear account settings](https://linear.app/larry-hudson/settings/account/security) - click 'New API key' under 'Personal API keys'.
2. Configure the MCP server in your code editor as shown below.
### Using with VS Code
One click install:
[](https://insiders.vscode.dev/redirect/mcp/install?name=linear&inputs=%5B%7B%22id%22%3A%22linear_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Linear%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40larryhudson%2Flinear-mcp-server%22%5D%2C%22env%22%3A%7B%22LINEAR_API_KEY%22%3A%22%24%7Binput%3Alinear_api_key%7D%22%7D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=linear&inputs=%5B%7B%22id%22%3A%22linear_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Linear%20API%20Key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40larryhudson%2Flinear-mcp-server%22%5D%2C%22env%22%3A%7B%22LINEAR_API_KEY%22%3A%22%24%7Binput%3Alinear_api_key%7D%22%7D%7D&quality=insiders)
Add this to your settings JSON file:
```json
{
"mcp": {
"inputs": [
{
"type": "promptString",
"id": "linear_api_key",
"description": "Linear API Key",
"password": true
}
],
"servers": {
"linear": {
"command": "npx",
"args": [
"-y",
"@larryhudson/linear-mcp-server"
],
"env": {
"LINEAR_API_KEY": "${input:linear_api_key}"
}
}
}
}
}
```
### Using with Cursor IDE
Add this to the MCP config JSON file:
```json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@larryhudson/linear-mcp-server"],
"env": {
"LINEAR_API_KEY": "<YOUR_API_KEY>"
}
}
}
}
```
### Using with Claude Desktop App
Add this to your MCP configuration JSON file:
```json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": [
"-y",
"@larryhudson/linear-mcp-server"
],
"env": {
"LINEAR_API_KEY": "<YOUR_API_KEY>"
}
}
}
}
```
### Using with Cline VS Code Extension
Add this to the MCP config JSON file:
```json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@larryhudson/linear-mcp-server"],
"env": {
"LINEAR_API_KEY": "<YOUR_API_KEY>"
},
"disabled": false,
"autoApprove": []
}
}
}
```
### Environment Variables
- `LINEAR_API_KEY` - Your Linear API key (required)
## How It Works
The server is built on the following key technologies:
- **Model Context Protocol (MCP)** - Framework for allowing AI assistants to interact with external tools and APIs
- **Linear SDK** - Client library for communicating with the Linear API
- **Node.js** - JavaScript runtime environment
- **Zod** - Type validation library for tool parameters
## Key Features
### Ticket Retrieval
- Gets comprehensive ticket details including status, priority, assignee, and team
- Fetches the full description and all comments
- Processes Markdown content with embedded images
- Downloads and includes images from ticket descriptions
### Issue Listing
- Retrieves issues assigned to the current user
- Filters by state (active, backlog, completed, canceled, or all)
- Returns a formatted table with key information about each issue
### Comment Addition
- Allows adding new comments to existing tickets
- Provides confirmation of successful comment creation
## Technical Implementation Details
1. **Image Handling**
- Extracts image URLs from Markdown using regular expressions
- Downloads images to a local temp directory
- Converts images to base64 for inclusion in MCP responses
- Uses MD5 hashing of URLs to create unique filenames
2. **Linear API Integration**
- Authenticates using a Linear API key
- Retrieves issues, tickets, comments, and user information
- Formats data for human-readable display
3. **Error Handling**
- Gracefully handles API errors, missing tickets, and download failures
- Provides meaningful error messages to the user
## Running the Server
The server communicates with Claude through standard input/output (stdio) using the MCP protocol. It requires:
- A Linear API key (configured in the code)
- Node.js runtime environment
- The dependency packages specified in package.json
## Project Structure
This is a relatively simple Node.js application with a single main source file (`index.ts`) that defines the MCP server, tools, and associated helper functions. It uses TypeScript for type safety and better developer experience.
## Dependencies
- `@modelcontextprotocol/sdk`: Core MCP implementation
- `@linear/sdk`: Linear API client
- `dotenv`: Environment variable management
- `node-fetch`: HTTP client for image downloads
- `zod`: Schema validation for tool parameters
## Limitations and Potential Improvements
- There's limited pagination support for large result sets (currently limited to 20 issues)
- Error handling could be improved for various edge cases
- The image downloading could benefit from better MIME type detection
- Consider adding more tools for managing issues (updating status, changing assignees, etc.)
- Support for attachments when creating issues or adding comments
