Linear MCP Orchestration Engine

This server acts as a dedicated conduit for AI agents leveraging the Model Context Protocol (MCP) to interface with the Linear project management ecosystem.

Core Capabilities

The following atomic operations are exposed via the MCP interface:

create_new_ticket

Instantiates a novel issue within Linear: - title (essential): The subject heading for the new item. - team_identifier (essential): The unique identifier of the team receiving the ticket. - body_content (optional): Detailed narrative for the issue (Markdown formatting is permissible). - urgency_level (optional): Numerical priority setting (range: 0 to 4). - initial_state (optional): The designated starting workflow status.

discover_tickets

Enables complex, paginated retrieval of existing issues using versatile criteria: - search_terms (optional): Textual query matching against titles or descriptions. - team_scope (optional): Filter results strictly by a specific team ID. - status_filter (optional): Constrain results based on their current state. - assigned_agent_id (optional): Filter by the individual assigned to the task. - priority_range (optional): Filter based on the defined priority range (0-4). - page_size (optional, default: 10): Maximum number of records returned per request. - pagination_token (optional): Token required for subsequent page retrieval. - ordering_field (optional, default: 'updated'): Attribute used for sorting ('created', 'updated', 'priority', 'title'). - order_direction (optional, default: 'desc'): Specifies ascending ('asc') or descending ('desc') order.

fetch_current_iteration_tasks

Retrieves all associated work items currently scoped within the active sprint/iteration: - team_identifier (essential): The requisite team ID.

locate_teams

Searches and returns metadata for Linear team entities: - team_name_pattern (optional): Pattern matching against team names for identification.

filter_active_iteration_by_status

Filters tasks within the present iteration based on status, applying an implicit filter for the invoking user's context: - team_identifier (essential): The requisite team ID. - status_designator (essential): The specific status value for filtering (e.g., "Awaiting QA").

retrieve_detailed_ticket_metadata

Fetches comprehensive attributes for a singular issue, including full narrative, associated commentary, and contextual metadata: - ticket_reference_id (essential): The unique Linear identifier (e.g., "ENG-999").

bulk_transition_ticket_state

Atomically modifies the workflow status for a specified collection of issues: - ticket_reference_list (essential): Array of issue IDs targeted for modification (e.g., ["ENG-123", "DATA-456"]). - destination_state (essential): The resultant workflow status to enforce (e.g., "In Development").

cycle_lifecycle_management

Handles the creation, modification, retrieval, or listing of Linear development cycles (sprints): - operation_type (essential): Action to execute: "create", "update", "fetch", or "list_all". - team_identifier (essential): The team context for the cycle operation. - cycle_reference_id (optional, mandatory for update/fetch): The specific Cycle ID. - cycle_designation (optional, mandatory for create): The human-readable name for the cycle. - start_date_iso (optional, mandatory for create): The cycle commencement date in ISO format (YYYY-MM-DD). - end_date_iso (optional, mandatory for create): The cycle conclusion date in ISO format (YYYY-MM-DD). - cycle_summary (optional): A descriptive summary for the cycle.

Deployment and Operational Guidance

1. Acquire your Linear access token from your Linear settings interface (API section).
2. Establish a configuration file named .env in the root directory:

LINEAR_API_KEY=your_secret_token_here

1. Install necessary runtime components: bash npm install

2. Initiate the service: bash

Debug/Development execution with hot-reload

npm run dev

Standard production execution

npm start

Compile TypeScript sources

npm run build

Linting checks

npm run lint

Unit and integration tests

npm run test

Inspect service execution environment

npm run inspect

Internal Architecture & Robustness

• Engineered using TypeScript and the MCP Framework SDK.
• Leverages the official Linear SDK for all external API communication.
• Features integrated exception management, request throttling, and persistent connection monitoring.
• Implements configurable retry logic for transient communication failures.
• Includes active monitoring probes to verify connection viability.
• Detailed operational logging available when running in verbose/debug modes.
• Incorporates an internal, transient data persistence layer to enhance retrieval latency.
• Native support for managing large data volumes via result pagination.
• Utilizes optimized batch processing algorithms for grouped actions.

Performance Layer

Transient Data Storage

• Utilizes an in-memory cache for frequently solicited reference data (team metadata, workflow mappings).
• Cache entries possess a configurable Time-To-Live (TTL).
• Automated routine for purging stale cache entries.
• Exposure of cache utilization metrics in diagnostics mode.

Resiliency Features

• Protective measures against API request timeouts, with adjustable threshold settings.
• Automated attempt cycle resumption upon detected connection interruption.
• Verbose error logging, timestamped and context-rich.
• Protocol for safe system termination, ensuring resource cleanup.
• Constant connection health verification via periodic ping/heartbeat checks.

Speed Optimizations

• Streamlined batch processing for multi-item modifications.
• Built-in mechanism for result set pagination.
• Exploitation of concurrent execution patterns using Promise.all for parallel fetching.
• Efficient data acquisition strategy minimizing redundant API calls.

External Libraries

• @linear/sdk: Primary client for interacting with the Linear API.
• @modelcontextprotocol/sdk: Core framework implementation.
• zod: Schema validation at runtime.
• dotenv: Handling of environment configuration secrets.
• Standard TypeScript toolchain.

Refer to package.json for the complete dependency manifest.

Smithery Deployment Pipeline

Deployment is facilitated via the Smithery.ai platform, utilizing included configuration artifacts:

Pre-requisites

• Active Smithery.ai credential set.
• Valid Linear API access credential.

Deployment Workflow

1. Integrate this repository source into your Smithery workspace or claim the existing server instance.
2. Navigate to the Deployment Management interface (access restricted to owners).
3. Configure the runtime environment using your Linear API key.
4. Initiate the deployment sequence.

Configuration Artifacts

The repository contains two crucial deployment specification files:

1. Dockerfile: Defines the container image creation procedure:
2. Base image: Node.js 18 based on Alpine for minimal footprint.
3. Steps: Dependency installation and TypeScript compilation.

4. Entry point: Command to launch the service process.

5. smithery.yaml: Specifies the execution environment setup:

6. Defines the startup command (npm start).
7. Declares required external configuration variables (the Linear API key).
8. Manages environment variable injection.

Local Verification

Use the MCP Inspector or Docker to validate the setup locally:

bash

Build the dedicated execution container image

docker build -t linear-mcp-service .

Execute the container, injecting the secret key

docker run -e LINEAR_API_KEY=your_key_here linear-mcp-service

Alternatively, use the integrated Inspector tool

npm run inspect