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

Features

• Issue Management

  • Create new issues with customizable properties (title, description, team, assignee, priority, labels, status)
  • List issues with flexible filtering options (team, assignee, status)
  • Update existing issues (title, description, status, assignee, priority)
  • Get detailed information about specific issues
  • Search issues using text queries

• Team Management

  • List all teams in the workspace
  • Access team details including ID, name, key, and description
  • List workflow states for each team

• Project Management

  • List all projects with optional team filtering
  • View project details including name, description, state, and associated teams

Prerequisites

• Node.js (v16 or higher)
• A Linear account with API access
• Linear API key with appropriate permissions

Quick Start

1. Get your Linear API key from Linear's Developer Settings

2. Run with your API key:

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

Or set it in your environment:

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

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 testing:

./run.sh

Then run the inspector:

npm run inspector

Configuration

Configure the MCP server in your settings file based on your client:

For Claude Desktop

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %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)

Location: ~/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)

For Cursor, the server must be run with the full path:

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

Available Tools

create_issue

Creates a new issue in Linear.

{
  title: string;          // Required: Issue title
  description?: string;   // Optional: Issue description (markdown supported)
  teamId: string;        // Required: Team ID
  assigneeId?: string;   // Optional: Assignee user ID
  priority?: number;     // Optional: Priority (0-4)
  labels?: string[];     // Optional: Label IDs to apply
  status?: string;       // Optional: Status name (e.g., "In Progress", "Done")
}

linear_list_issues

Lists issues with optional filters.

{
  teamId?: string;      // Optional: Filter by team ID
  assigneeId?: string;  // Optional: Filter by assignee ID
  status?: string;      // Optional: Filter by status
  first?: number;       // Optional: Number of issues to return (default: 50)
}

linear_update_issue

Updates an existing issue.

{
  issueId: string;       // Required: Issue ID
  title?: string;        // Optional: New title
  description?: string;  // Optional: New description
  status?: string;       // Optional: New status name (e.g., "In Progress", "Done")
  assigneeId?: string;   // Optional: New assignee ID
  priority?: number;     // Optional: New priority (0-4)
  labels?: string[];     // Optional: Label IDs to apply to the issue
}

Note: The status parameter accepts human-readable status names (e.g., "Todo", "In Progress", "Done", "Canceled"). The tool will automatically convert these to the appropriate Linear state IDs.

linear_list_teams

Lists all teams in the Linear workspace. No parameters required.

linear_list_projects

Lists all projects with optional filtering.

{
  teamId?: string;     // Optional: Filter by team ID
  first?: number;      // Optional: Number of projects to return (default: 50)
}

linear_get_issue

Gets detailed information about a specific issue.

{
  issueId: string; // Required: Issue ID
}

linear_list_workflow_states

Lists all workflow states for a specific team.

{
  teamId: string; // Required: Team ID
}

Returns the available workflow states (e.g., "Backlog", "Todo", "In Progress", "In Review", "Done", "Canceled", "Duplicate") that can be used when creating or updating issues.

Development

For development with auto-rebuild:

npm run watch

Error Handling

The server includes comprehensive error handling for:

• Invalid API keys
• Missing required parameters
• Linear API errors
• Invalid tool requests

All errors are properly formatted and returned with descriptive messages.

Technical Details

Built with:

• TypeScript
• Linear SDK (@linear/sdk v37.0.0)
• MCP SDK (@modelcontextprotocol/sdk v0.6.0)

The server uses stdio for communication and implements the Model Context Protocol for seamless integration with AI agents.

License

MIT