Skip to content

README.md

Latest commit

 

History

History
213 lines (167 loc) · 7.33 KB

README.md

File metadata and controls

213 lines (167 loc) · 7.33 KB

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:

Filter Description Example
first Max results (default: 50) {"first": 10}
after Cursor for forward pagination {"after": "cursor_string"}
teamId Filter by team ID {"teamId": "team-uuid"}
id Filter by specific project ID(s) {"id": ["proj-uuid"]}
name Filter by project name (contains) {"name": "Refactor"}
state Filter by project state {"state": "started"}
health Filter by project health {"health": "onTrack"}
priority Filter by priority (0-4) {"priority": 3}
createdAfter Filter by creation date (ISO 8601) {"createdAfter": "2023-01-01"}
createdBefore Filter by creation date (ISO 8601) {"createdBefore": "2024-01-01"}
updatedAfter Filter by update date (ISO 8601) {"updatedAfter": "2023-06-01"}
updatedBefore Filter by update date (ISO 8601) {"updatedBefore": "2024-01-01"}
orderBy Sort results by field {"orderBy": "createdAt"}

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