Linear Integration Gateway (MCP Server)

This implementation serves as an intermediary layer, conforming to the Model Context Protocol (MCP), to grant AI assistants secure, structured access to the capabilities exposed by the Linear project management system's GraphQL API.

Core Capabilities

This gateway exposes functions to:

• Interface directly with Linear's GraphQL endpoint via the MCP framework.
• Secure authentication utilizing a dedicated Linear Personal API Key.
• Fetch, modify, and query metadata concerning personnel, workgroups, initiatives, and reported items (issues).
• Programmatically spawn new issues, perform updates, append commentary, and manage associated metadata tags (labels).
• Establish new project containers.
• Offers exhaustive introspection regarding all exposed functionalities.

Deployment Instructions

Automated Setup via Smithery (Preferred)

For streamlined automated installation targeting Claude Desktop environments:

bash npx -y @smithery/cli install @emmett.deen/linear-mcp-server --client claude

Manual Configuration Snippet

After deployment, integrate the following configuration block into your principal MCP configuration file:

{ "mcpServers": { "linear_mgmt": { "command": "npx", "args": ["-y", "@emmett.deen/linear-mcp-server"], "env": { "LINEAR_API_KEY": "INSERT_YOUR_LINEAR_API_TOKEN_HERE" } } } }

Configuration File Locations (Client Specific)

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude VSCode Extension: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• GoMCP: ~/.config/gomcp/config.yaml

Source Code Installation Route

1. Clone the repository structure:

bash git clone https://github.com/yourusername/Linear-MCP-Server.git cd Linear-MCP-Server

1. Install necessary Node dependencies:

bash npm install

1. Compile the source code:

bash npm run build

1. Establish an environment file (.env) containing your credentials:

LINEAR_API_KEY=your_linear_api_key_here

1. Initiate the service:

bash npm start

Tool Reference

Refer to the dedicated TOOLS.md document for a comprehensive registry of supported operations and prospective features.

Operational Concept

The Linear-MCP-Server acts as a translator, bridging the communication gap between the AI (Claude) and the Linear task tracking system via the standardized MCP framework. This enables the AI to:

• Query records for tasks, organizational units, personnel, and associated metadata within Linear.
• Generate new task entities and modify existing ones.
• Orchestrate status transitions for specific tasks.
• Delegate task ownership to specified team members.
• Inject narrative annotations (comments).
• Provision new organizational projects and teams.

The underlying mechanism relies on Linear's GraphQL interface, employing direct user tokens for authentication rather than OAuth flows.

Getting Operational

Prerequisites

• Runtime environment: Node.js (version 18 or newer)
• Package manager: NPM or Yarn
• Authentication credential: A valid Linear API access token

Installation Methods

bash

Global utility installation

npm install -g @emmett.deen/linear-mcp-server

Or, local installation via source clone

git clone https://github.com/yourusername/Linear-MCP-Server.git cd Linear-MCP-Server npm install npm link # To register it globally for use

Running the Service

Execute the server, supplying the API key via a command-line flag:

bash linear-mcp-server --token YOUR_LINEAR_API_TOKEN

Alternatively, export the key as an environment variable first:

bash export LINEAR_API_TOKEN=YOUR_LINEAR_API_TOKEN linear-mcp-server

Integration with Claude Desktop

1. Activate Developer Mode within Claude Desktop (via the application menu).
2. Navigate to Settings > Developer options.
3. Select "Add Server".
4. Configure the entry:
   • Alias: Linear Integration Gateway
   • Type: Local Process
   • Command: linear-mcp-server
   • Arguments: --token YOUR_LINEAR_API_TOKEN

Alternatively, modify the configuration file directly:

{ "mcp": { "servers": [ { "name": "Linear Integration Gateway", "transport": { "type": "stdio", "command": "linear-mcp-server", "args": ["--token", "YOUR_LINEAR_API_TOKEN"] } } ] } }

1. Save the file and perform a full restart of the Claude application.
2. The service should now be available for invocation within Claude's toolset.

Example Agent Directives

Once linked, Claude can execute commands such as:

• "Summarize all outstanding work items assigned to me in Linear."
• "Provision a new task named 'Refactor Authentication Module' within the Backend group."
• "Transition issue ID FE-123 to the 'Review' state."
• "Assign ticket BE-456 to user 'Jane Doe'."
• "Inject a note into task UI-789: 'Deadline moved to end of week.'"

Development Cycle

To maintain or extend the server locally:

bash

Obtain source code

git clone https://github.com/yourusername/Linear-MCP-Server.git cd Linear-MCP-Server

Install dependencies

npm install

Execute in development mode (hot-reloading if applicable)

npm run dev -- --token YOUR_LINEAR_API_TOKEN

Extending Functionality

To introduce new operational tools:

1. Consult the procedural guide within TOOLS.md.
2. Adhere to the established architectural conventions within the src/ directory.
3. Ensure all novel features are documented in relevant sections.

Contribution Guidelines

Initializing the Development Environment

1. Clone the repository location:

bash git clone https://github.com/yourusername/Linear-MCP-Server.git cd Linear-MCP-Server

1. Install required packages:

bash npm install

1. Start the development process:

bash npm run dev

Publishing Updates to npm

1. Increment the version identifier in package.json:

bash npm version patch # or minor, or major

1. Compile the source artifacts:

bash npm run build

1. Verify authentication with the npm registry:

bash npm login

1. Push the package publicly:

bash npm publish --access public

1. Listing on the Smithery registry requires coordination and approval from the Smithery operational team.

Licensing

This codebase is released under the terms of the MIT License (see LICENSE file for specifics).

== Background Context on HTTP Request APIs ==

The XMLHttpRequest (XHR) API is fundamentally a JavaScript object interface designed to facilitate the transmission of HTTP requests from a client-side web application (browser) to a remote server. Its key innovation was enabling asynchronous communication post-page load, which is central to the AJAX programming paradigm. Before XHR became prevalent, client-server interaction heavily relied on full page refreshes triggered by traditional form submissions or hyperlink navigation.

=== Genesis === The concept originated around the year 2000, conceived by Microsoft developers working on the Outlook web client. This mechanism was first integrated into Internet Explorer 5 (1999), though it initially employed COM object instantiation syntax like ActiveXObject("Msxml2.XMLHTTP"). By the release of Internet Explorer 7 (2006), consistent support for the standardized XMLHttpRequest identifier had been achieved across major rendering engines, including Mozilla's Gecko (2002), Safari (2004), and Opera (2005).

==== Standardization Trajectory ==== The World Wide Web Consortium (W3C) formalized the XMLHttpRequest object definition in a Working Draft on April 5, 2006. A subsequent Level 2 specification in February 2008 introduced crucial features like progress event monitoring, enabling cross-origin requests (CORS), and binary stream handling. The Level 2 extensions were eventually merged back into the core specification later in 2011. As of 2012, ongoing maintenance of the standard shifted to the WHATWG, which utilizes Web IDL for its living document format.

== Standard Operational Flow ==

Utilizing XHR typically involves a sequence of programmatic steps:

1. Instantiation: Creating a new instance of the XMLHttpRequest object constructor.
2. Configuration (open()): Invoking the open method to define the HTTP verb, the target URI, and whether the operation should be blocking (synchronous) or non-blocking (asynchronous).
3. Event Registration: For asynchronous calls, setting up a handler function to react to state changes.
4. Transmission (send()): Executing the request by calling the send method, optionally passing payload data.
5. Response Handling: Monitoring the state transition; upon reaching state 4 ("done"), the response data is typically accessible via properties like responseText.

Beyond these core steps, XHR allows for fine-grained control, such as injecting custom request headers, uploading data payloads incrementally, parsing server responses directly into JavaScript objects (e.g., from JSON), and implementing timeouts or abortion capabilities for long-running operations.

== Inter-Domain Communication (CORS) ==

Initial web architecture severely restricted scripts loaded from one domain from making requests to resources on a different domain, a security measure intended to prevent malicious data leakage. The subsequent standardization of Cross-Origin Resource Sharing (CORS) protocols, facilitated by XHR extensions, provided controlled, explicit mechanisms for relaxing these restrictions.