Linear API Interaction Module

Note: This implementation is custom-built. For the official Cline version, consult the repository at cline/linear-mcp.

This Model Context Protocol (MCP) server furnishes agents with advanced capabilities to manipulate data within the Linear environment via its RESTful API. It empowers AI entities to execute sophisticated operations across issues, defined projects, and organizational teams.

Core Capabilities

• Task Administration (Issues)

• Instantiation: Generate new tickets incorporating configurable metadata (subject, detailed body, associated team, designated personnel, severity level, descriptive tags).

• Retrieval: Fetch itemized lists of tasks, allowing granular filtering based on team affiliation, assigned individual, or current workflow state.

• Modification: Adjust parameters of extant tickets, such as renaming, revising documentation, transitioning workflow stages, reassigning ownership, or altering priority ranking.

• Team Structure Querying

• Enumerate all active workgroups within the current workspace.

• Retrieve comprehensive details for any group, including its unique identifier, nomenclature, short-form key, and descriptive narrative.

• Project Lifecycle Oversight

• Produce comprehensive inventories of ongoing projects, optionally scoped to a particular team.
• Access granular data for any project, such as its title, scope description, current completion status, and linked workgroups.

Operational Requirements

• Execution environment must possess Node.js (version 16 or newer).
• Access credentials for a Linear account are mandatory.
• A valid Linear API key granting necessary operational permissions.

Initial Setup Guidance

1. Procure your authentication token from Linear Developer Settings.

2. Initiate execution using the API key:

bash LINEAR_API_KEY=your-api-key npx @ibraheem4/linear-mcp

Alternatively, set the environment variable externally:

bash export LINEAR_API_KEY=your-api-key npx @ibraheem4/linear-mcp

Local Development Environment Configuration

1. Obtain repository source code:

bash git clone [repository-url] cd linear-mcp

1. Install required packages:

bash npm install

1. Compile the source code:

bash npm run build

Debugging with the MCP Inspector

For local iteration and inspection:

1. Install the supergateway utility:

bash npm install -g supergateway

1. Employ the bundled execution script:

bash chmod +x run.sh LINEAR_API_KEY=your-api-key ./run.sh

1. Connect to the diagnostic interface:
2. Navigate to http://localhost:1337
3. Communication utilizes Server-Sent Events (SSE).
4. Test and validate tool invocations directly within the Inspector UI.

Client Configuration Directives

Configure the server endpoint details within your client's settings file, depending on the application:

For Claude Desktop

• MacOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows Path: %APPDATA%/Claude/claude_desktop_config.json

{ "mcpServers": { "linear-mcp": { "command": "node", "args": ["/path/to/linear-mcp/build/index.js"], "env": { "LINEAR_API_KEY": "your-api-key-here" }, "disabled": false, "alwaysAllow": [] } } }

For VS Code Extension (Cline)

Path: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

{ "mcpServers": { "linear-mcp": { "command": "node", "args": ["/path/to/linear-mcp/build/index.js"], "env": { "LINEAR_API_KEY": "your-api-key-here" }, "disabled": false, "alwaysAllow": [] } } }

For Cursor (cursor.sh)

Execution requires specifying the absolute location of the compiled entry point:

bash node /Users/ibraheem/Projects/linear-mcp/build/index.js

Available Service Functions

create_issue

Registers a novel ticket within Linear.

typescript { title: string; // Mandatory: The subject line for the ticket description?: string; // Optional: Detailed content (supports Markdown formatting) teamId: string; // Mandatory: Identifier for the responsible team assigneeId?: string; // Optional: User ID designated as the primary handler priority?: number; // Optional: Severity ranking (scale 0 through 4) labels?: string[]; // Optional: Array of existing Label IDs to associate }

list_issues

Retrieves a collection of tasks, subject to optional constraints.

typescript { teamId?: string; // Optional: Filter results exclusively to this team's tasks assigneeId?: string; // Optional: Filter results to tasks assigned to this user status?: string; // Optional: Filter by the current workflow state first?: number; // Optional: Limit the quantity of records returned (Default set to 50) }

update_issue

Modifies attributes of an existing work item.

typescript { issueId: string; // Mandatory: Unique identifier of the item to modify title?: string; // Optional: New title value description?: string; // Optional: Revised descriptive text status?: string; // Optional: New positional state in the workflow assigneeId?: string; // Optional: Reassign ownership to a different user ID priority?: number; // Optional: Updated severity level (0-4) }

list_teams

Fetches the complete roster of configured teams. No input arguments are necessary.

list_projects

Returns a catalog of active projects, with optional filtering capability.

typescript { teamId?: string; // Optional: Scope the list to projects belonging to this team first?: number; // Optional: Maximum count of projects to retrieve (Default is 50) }

get_issue

Retrieves the comprehensive data payload for one specific task.

typescript { issueId: string; // Mandatory: The specific ID of the task requested }

Development Cycle

To initiate development with automatic source code recompilation upon change:

bash npm run watch

Fault Tolerance Mechanisms

The server incorporates robust handling for anticipated operational failures, specifically addressing:

• Invalid or expired API authentication credentials.
• Missing parameters required by a specific tool invocation.
• Errors returned directly from the upstream Linear API service.
• Malformed requests directed to the tool interface.

All exceptions are processed to yield structured, descriptive error messages back to the caller.

Implementation Specifications

Technologies utilized in construction:

• Programming Language: TypeScript
• Core SDK: Linear SDK (version 37.0.0)
• Protocol Handler: MCP SDK (@modelcontextprotocol/sdk version 0.6.0)

The communication channel is established over standard input/output (stdio), adhering strictly to the Model Context Protocol specification for smooth integration with autonomous agents.

Licensing Information

This package is distributed under the MIT License.

Business Contextualization (WIKIPEDIA)

Business management systems encompass the entire spectrum of applications, methodologies, calculation mechanisms, and controls utilized by commercial entities to maintain market relevance, optimize competitive standing, and enhance overall operational effectiveness in dynamic environments. These systems can be functionally segregated across departmental lines, covering areas such as process governance, resource allocation, data recording, strategic planning, and performance oversight.

Modern enterprise tools have undergone rapid transformation driven by technological acceleration. This proliferation makes tool selection challenging; managers must adopt a strategic, adaptive approach rather than blindly adopting the newest technology. Selection must prioritize alignment with core organizational objectives over mere feature parity.

Historical data from 2013 (Bain & Company survey) indicated prevalent global management priorities included Strategic Planning, CRM, Employee Feedback mechanisms, Benchmarking, and Supply Chain optimization.

Software applications for businesses began with foundational Management Information Systems (MIS), evolving into comprehensive Enterprise Resource Planning (ERP) suites, later integrating Customer Relationship Management (CRM), and now heavily migrating toward cloud-based management platforms. Value realization from IT investments hinges critically on two factors: the efficiency of the deployment process and the wisdom applied in choosing and customizing the requisite tools.