Linear MCP Server

Note: This is a custom implementation. For the official Cline Linear MCP server, see cline/linear-mcp.

A Model Context Protocol (MCP) server that provides tools for interacting with Linear's API, enabling AI agents to manage issues, projects, teams, and more programmatically.

Installation

Prerequisites

• Node.js (v16 or higher)

• A Linear account with API access

• Linear API key with appropriate permissions (get from Linear's Developer Settings)

Usage

Quick Start

You need to provide your Linear API key to the server.

Option 1: Command Line Argument

LINEAR_API_KEY=your-api-key npx @gmclend/linear-mcp

Option 2: Environment Variable

export LINEAR_API_KEY=your-api-key
# Then run the server
npx @gmclend/linear-mcp

Client Configuration

Configure your MCP client (e.g., in its settings file) to connect to this server:

{
  "mcpServers": {
    "linear-mcp": {
      "command": "npx",
      "args": ["-y", "@gmclend/linear-mcp"],
      "env": {
        "LINEAR_API_KEY": "your-api-key-here",
        // Optional: Enable read-only mode (see below)
        "LINEAR_MCP_READ_ONLY": "false" 
      }
    }
  }
}

Read-Only Mode

Run the server in read-only mode to prevent accidental modifications and limit the available tools (useful in restricted environments). Set the LINEAR_MCP_READ_ONLY environment variable:

LINEAR_MCP_READ_ONLY=true LINEAR_API_KEY=your-api-key npx @gmclend/linear-mcp

Features

This server provides comprehensive tools for managing various Linear entities:

• Issue Management: Create, list (with filters), update, and search issues.

• Comment Management: Create, view, update, and delete comments on issues.

• Label Management: List, create, and update team labels.

• Team Management: List teams and view team details.

• Project Management: List projects (with filters) and view project details.

• Cycle Management: List, create, and update team cycles.

• Document Management: List, create, and update project documents.

• User Management: List users, get user details, and get info about the authenticated user.

• Roadmap/Initiative Management: List roadmaps/initiatives and get details.

Available Tools

All tools are defined in src/tools/definitions.ts.

Read-Only Tools

(Available in both standard and read-only modes)

• list_issues: List issues with optional filters (team, assignee, status, priority, etc.).

• search_issues: Search issues using query text.

• get_issue: Get detailed information about a specific issue.

• get_comment: Get a specific comment.

• list_labels: List all labels in a team.

• get_label: Get label details.

• list_teams: List all teams in the workspace.

• get_team: Get team details.

• list_projects: List all projects with optional filters (see Project Filters section).

• get_project: Get project details.

• list_cycles: List all cycles in a team.

• get_cycle: Get cycle details.

• list_documents: List all documents, optionally filtered by team.

• get_document: Get document details.

• list_users: List all users in the workspace.

• get_user: Get detailed information about a specific user.

• me: Get information about the authenticated user.

• list_roadmaps: List all roadmaps.

• get_roadmap: Get roadmap details.

• get_initiative: Get detailed information about a specific initiative.

Write Tools

(Only available when LINEAR_MCP_READ_ONLY is not true)

• create_issue: Create a new issue.

• update_issue: Update an existing issue (title, description, status, assignee, priority, labels).

• create_comment: Create a comment on an issue.

• update_comment: Update an existing comment.

• delete_comment: Delete a comment.

• create_label: Create a new label.

• update_label: Update an existing label.

• create_cycle: Create a new cycle.

• update_cycle: Update an existing cycle.

• create_document: Create a new document associated with a project.

• update_document: Update an existing document.

Filters and Pagination

Many list_* tools support filtering and pagination.

Project Filters (list_projects)

The list_projects command accepts the following filter parameters:

Example Response (list_projects):

{
  "projects": [
    {
      "id": "project-id",
      "name": "Project Name",
      // ... other fields
      "teams": [ { "id": "team-id", "name": "Team Name", "key": "TEAM" } ]
    }
  ],
  "pagination": {
    "hasNextPage": true,
    "endCursor": "cursor-for-next-page"
  }
}

Initiative Pagination (list_initiatives)

The list_initiatives tool supports pagination:

• first: Number of items from the beginning (default: 50).

• last: Number of items from the end.

• after: Cursor for forward pagination.

• before: Cursor for backward pagination.

Example Response (list_initiatives):

{
  "initiatives": [ /* ... initiative data ... */ ],
  "pagination": {
    "hasNextPage": true,
    "hasPreviousPage": false,
    "startCursor": "cursor-for-first-item",
    "endCursor": "cursor-for-last-item"
  }
}

Development

Setup

1. Clone the repository: git clone [repository-url] && cd linear-mcp

2. Install dependencies: npm install

3. Build the project: npm run build

Running with Inspector

For local development and debugging with a web UI:

npm run inspector

Open http://localhost:6274 in your browser.

Auto-Rebuild

For development with auto-rebuild on file changes:

npm run watch

Technical Details

• Built with TypeScript, Linear SDK (@linear/sdk), and MCP SDK (@modelcontextprotocol/sdk).

• Communicates via stdio using the Model Context Protocol.

• Includes basic error handling for API keys, parameters, and Linear API issues.

License

MIT