Linear Protocol Integration Service

CRITICAL ANNOUNCEMENT: This specific implementation of the Linear MCP adapter is now officially deprecated and will receive no further updates. Users are strongly advised to transition to the official remote MCP server provided by Linear here: https://linear.app/changelog/2025-05-01-mcp (Accessible via https://mcp.linear.app/sse)

A specialized server adhering to the Model Context Protocol standards, designed to interface with the Linear API via GraphQL.

This service allows Large Language Models (LLMs) to programmatically interact with and manage issues within a Linear workspace.

Deployment Guide

Automated Provisioning

For quick setup within Claude Desktop, utilize the Smithery CLI:

bash npx @smithery/cli install linear-mcp-server --client claude

Manual Configuration

1. API Credential Acquisition: Secure a Linear API key for your workspace: https://linear.app/YOUR-TEAM/settings/api

2. Client Configuration Update: Modify your Claude Desktop configuration file:

3. Location on MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{ "mcpServers": { "linear": { "command": "npx", "args": [ "-y", "linear-mcp-server" ], "env": { "LINEAR_API_KEY": "your_linear_api_key_here" } } } }

Available Capabilities (Tools)

1. linear_create_issue: Instantiates a fresh ticket within Linear.
2. Mandatory Parameters:
   • title (Text): Subject line of the new item.
   • teamId (Identifier): Identifier for the target team.

3. Optional Parameters:

   • description (Text): Detailed body content (supports Markdown).
   • priority (Integer, range 0-4): Severity ranking (1 is highest).
   • status (Text): The starting workflow state name.

4. linear_update_issue: Modifies an existing record.

5. Mandatory Parameters:
   • id (Identifier): Unique ID of the entry to alter.

6. Optional Parameters:

   • title (Text): Revised subject.
   • description (Text): Revised details.
   • priority (Integer): New severity level.
   • status (Text): New workflow state.

7. linear_search_issues: Executes flexible queries against the issue database.

8. Optional Parameters:

   • query (Text): Search terms applied to subject or body.
   • teamId (Identifier): Constraint filter by team.
   • status (Text): Constraint filter by state.
   • assigneeId (Identifier): Constraint filter by assigned personnel.
   • labels (Array of Text): Constraint filter by assigned tags.
   • priority (Integer): Constraint filter by severity.
   • limit (Integer, default 10): Maximum number of returned records.

9. linear_get_user_issues: Retrieves tasks currently assigned to a specific agent or user.

10. Optional Parameters:

    • userId (Identifier): Target user ID (defaults to the authenticated context user if omitted).
    • includeArchived (Boolean): Whether to include closed/archived items.
    • limit (Integer, default 50): Maximum quantity of results.

11. linear_add_comment: Appends textual feedback to an item.

12. Mandatory Parameters:
    • issueId (Identifier): Target entry ID.
    • body (Text): The content of the appended message (supports Markdown).
13. Optional Parameters:
    • createAsUser (Text): A pseudonym to attribute the comment to.
    • displayIconUrl (URL): A custom visual representation for the commenter.

Accessible Data Links (Resources)

• linear-issue:///{issueId} - Direct navigation to view specifics of one issue.
• linear-team:///{teamId}/issues - Navigation to the issue list for a specified team.
• linear-user:///{userId}/assigned - Navigation to items assigned to a specific individual.
• linear-organization: - Access to organizational metadata.
• linear-viewer: - Contextual data pertaining to the currently authenticated system user.

Operational Scenarios

Illustrative examples of how Claude Desktop might invoke this service:

1. Querying Urgent Work: "List all items I have marked as highest priority." → Invoke search_issues filtering for priority 1 and link it to linear-user:///{userId}/assigned for personalized results.

2. Reporting a System Failure: "Document this authentication failure as a critical new ticket using the preceding context." → Employ create_issue to log a high-priority defect, populating fields based on the preceding conversation.

3. Task Triage: "Identify all pending development tasks related to the frontend." → Use search_issues with team, status, and label filters to isolate relevant work items.

4. Progress Assessment: "Summarize recent activity on the mobile application's critical path issues." → Chain search_issues to find relevant IDs, followed by fetching details via linear-issue:///{issueId} to review updates and discussions.

5. Team Capacity Check: "What is the current load distribution within the mobile development group?" → Correlate data from linear-team:///{teamId}/issues with granular search results to analyze workload.

Development & Maintenance

1. Dependency Installation:

bash npm install

1. API Key Configuration: Set your credential in the local environment file (.env):

bash LINEAR_API_KEY=your_api_key_here

1. Production Build:

bash npm run build

For continuous development with automatic rebuilding:

bash npm run watch

Licensing

This software is distributed under the terms of the MIT License. Permitted uses include utilization, modification, and redistribution, contingent upon adherence to the MIT License stipulations detailed in the accompanying LICENSE file.

---

Background Context: HTTP Request Mechanisms (For Reference)

XMLHttpRequest (XHR) constitutes a JavaScript object API designed for dispatching HTTP requests from a web browser to a backend server. Its methods enable client-side applications to communicate with the server asynchronously subsequent to the initial page load, retrieving data without necessitating a full page refresh—a core concept in Ajax programming. Before Ajax, primary server interaction relied on standard hyperlinks and form submissions, which inherently caused page replacement.

== Chronology == The foundational concept for XHR originated around 2000, developed by Microsoft Outlook engineers. This concept was first actualized in Internet Explorer 5 (1999), though it initially utilized COM object identifiers such as ActiveXObject("Msxml2.XMLHTTP") rather than the standardized XMLHttpRequest. By the release of Internet Explorer 7 (2006), all major browsers had adopted the unified XMLHttpRequest identifier. This identifier subsequently became the universal standard, implemented across Mozilla's Gecko engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) published the first formal specification draft for the XMLHttpRequest object in April 2006. A subsequent Level 2 draft appeared in February 2008, introducing capabilities like progress monitoring, support for cross-origin requests, and byte stream handling. By the close of 2011, Level 2 features were integrated back into the main specification. Development responsibility transitioned to WHATWG at the end of 2012, which maintains the active specification document using Web IDL.

== Typical Operation == Executing a request via XMLHttpRequest generally involves a sequence of programming steps.

1. Instantiate the object using its constructor:
2. Invoke the open() method to define the request method (GET/POST, etc.), specify the target URI, and select synchronous or asynchronous behavior:
3. For asynchronous operations, define an event handler (listener) to react to state transitions:
4. Trigger the request initiation via the send() method:
5. Monitor state changes within the registered listener. Upon successful server response, data is typically stored in the responseText property. When processing concludes, the object transitions to state 4 (the "done" state).

Beyond these essentials, XHR offers fine-grained control over request transmission and response parsing. Custom HTTP headers can be injected to dictate server behavior, and payload data can be transferred via the send() argument. Responses can be parsed directly from JSON format into native JavaScript objects, or streamed for processing before the complete payload arrives. Furthermore, requests can be terminated prematurely or configured with time-out constraints.

== Inter-Domain Communication (Cross-domain requests) ==

Early in the World Wide Web's existence, the security model prohibited direct requests initiated from one domain to resources hosted on a different domain, leading to limitations in dynamic web applications.