Linear MCP Server Again

🚀 Linear MCP Server

This project implements a Model Context Protocol (MCP) server that serves as a bridge between Claude and the Linear task/issue management system.

🚀 Quick Start

The Linear MCP Server allows Claude to interact with Linear through a set of tools, enabling seamless integration between the AI assistant and the project management platform.

✨ Features

Ticket Retrieval

• Retrieve comprehensive ticket details, including status, priority, assignee, and team.
• Fetch the full description and all comments.
• Handle Markdown content with embedded images.
• Download and include images from the ticket description.

Issue Listing

• Retrieve issues assigned to the current user.
• Filter by status (active, backlog, completed, cancelled, or all).
• Return a formatted table with key information for each issue.

Comment Addition

• Add new comments to existing tickets.
• Provide a confirmation message upon successful comment creation.

📦 Installation

No direct installation is required. When properly configured, the package will be automatically downloaded and used by your Claude integration.

💻 Usage Examples

Basic Usage

1. Obtain a Linear API key from your Linear Account Settings - click "New API Key" under "Personal API Keys".
2. Configure the MCP server in your code editor as follows:

Using VS Code

• get_ticket
  • Parameters: ticketId (string)
  • Output: A JSON object containing ticket details, comments, and embedded images.
• get_my_issues
  • Parameters: state (optional string, default "active")
  • Output: A tabular list of the current user's issues, sorted by priority.
• add_comment
  • Parameters: ticketId (string) and comment (string)
  • Output: A success confirmation message.
• create_issue
  • Parameters: title (string), description (string), priority (string, default "normal"), assigneeId (optional string), and teamId (optional string)
  • Output: Details of the created issue.

Using the VS Code Extension Cline

Add the following to your MCP configuration JSON file:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": [
        "-y",
        "@larryhudson/linear-mcp-server"
      ],
      "env": {
        "LINEAR_API_KEY": "<YOUR_API_KEY>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

📚 Documentation

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): A framework that allows AI assistants to interact with external tools and APIs.
• Linear SDK: A client library for communicating with the Linear API.
• Node.js: A JavaScript runtime environment.
• Zod: A library for type validation of tool parameters.

Technical Details

Image Processing

• Use regular expressions to extract image URLs from Markdown.
• Download images to a local temporary directory.
• Convert images to base64 for inclusion in MCP responses.
• Generate unique filenames using the MD5 checksum of the URL.

Linear API Integration

• Authenticate using the Linear API key.
• Retrieve issues, tickets, comments, and user information.
• Format data for human-readable display.

Error Handling

• Gracefully handle API errors, missing tickets, and download failures.
• Provide meaningful error messages to the user.

Running the Server

The server communicates with Claude via standard input/output (stdio) using the MCP protocol. It requires:

• A Linear API key (configured in the code).
• A Node.js runtime environment.
• Dependencies specified in the package JSON.

Project Structure

This is a relatively simple Node.js application with a single main source file (index.ts), which defines the MCP server, tools, and related helper functions. It uses TypeScript for type safety and a better developer experience.

Dependencies

• @modelcontextprotocol/sdk: Core of the 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

• Limited pagination support for large result sets (currently limited to 20 issues).
• Error handling can be improved for more edge cases.
• Image downloads could benefit from better MIME type detection.
• Consider adding more tools to manage issues (update status, change assignee, etc.).
• Support attachments when creating issues or adding comments.