@ibraheem4/linear-mcp

78.0.1 • Public • Published

Linear MCP Server

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)
    • List issues with flexible filtering options (team, assignee, status)
    • Update existing issues (title, description, status, assignee, priority)
  • Team Management

    • List all teams in the workspace
    • Access team details including ID, name, key, and description
  • 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

Installation

  1. Clone the repository:
git clone [repository-url]
cd linear-server
  1. Install dependencies:
npm install
  1. Build the project:
npm run build

Configuration

  1. Obtain a Linear API key:

    • Go to your Linear workspace settings
    • Navigate to the API section
    • Generate a new API key with appropriate permissions
  2. Configure the MCP server in your settings file based on your client:

For Cline (VS Code Extension)

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

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

For Roo Cline

Location: ~/Library/Application Support/Roo Cline/settings/cline_mcp_settings.json

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

For Claude Desktop

  • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "linear-server": {
      "command": "node",
      "args": ["/path/to/linear-server/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "your-api-key-here"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

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
}

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)
}

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
  assigneeId?: string;  // Optional: New assignee ID
  priority?: number;    // Optional: New priority (0-4)
}

list_teams

Lists all teams in the workspace. No parameters required.

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)
}

Development

For development with auto-rebuild:

npm run watch

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. The project includes the MCP Inspector for debugging:

npm run inspector

This will provide a URL to access debugging tools in your browser.

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 to help diagnose issues.

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.

Package Sidebar

Install

npm i @ibraheem4/linear-mcp

Weekly Downloads

85

Version

78.0.1

License

MIT

Unpacked Size

41.7 kB

Total Files

6

Last publish

Collaborators

  • ibraheem4