Linear MCP Server

A Model Context Protocol (MCP) server implementation that provides comprehensive access to Linear's issue tracking system through a standardized interface.

Features

$3

* Create new issues and subissues with label support
* Update existing issues with full field modification
* Delete issues with validation
* Self-assign issues using 'me' keyword
* Advanced search with Linear's powerful filtering capabilities
* Filter issues by cycle (current, next, previous, or specific cycle)
* Add comments to issues with markdown support
* Query Linear issues by ID or key with optional relationships

$3

* List projects with filtering and pagination
* Project updates with health status tracking
* Project milestones - Create, update, delete milestones

$3

* List users in workspace or by team
* Get user details (supports "me" for current user)
* Team members with role information
* List teams with name/key filtering

$3

* List initiatives
* Create and update initiatives
* Link/unlink projects to initiatives

$3

* List documents (workspace or project-specific)
* Create and update documents
* Markdown content support

$3

* List cycles for a team
* Get cycle details
* Create and update cycles
* Filter issues by cycle

$3

* List workflow states for a team
* List labels (workspace or team-specific)
* Create and update labels

$3

* List attachments for an issue
* Get attachment details
* Create, update, and delete attachments
* Support for custom metadata and icons

$3

* List notifications for current user
* Get notification details
* Mark notifications as read (single or all)
* Archive, snooze, and unsnooze notifications
* Get unread notification count

$3

* Get complete change history for any issue
* Track state, assignee, priority, and label changes
* See who made each change and when

Prerequisites

- Node.js v18+ or Bun runtime
- Linear account with API access
- Linear API key (generate at Linear Settings > API)

Installation

Install from npm:

``bash
npm install -g @calltelemetry/linear-mcp
`

Or use directly with npx (no installation required):

`bash
npx @calltelemetry/linear-mcp
`

Configuration

Configure the MCP server in your preferred AI coding assistant. You'll need your Linear API key.

$3

The server automatically loads environment variables from a .env file. Create ~/.env or .env in your project:

`bash
LINEAR_API_KEY=lin_api_xxxxxxxxxxxxx
`

Then configure your MCP client without the env block:

`json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@calltelemetry/linear-mcp"]
}
}
}
`

$3

Alternatively, pass the API key directly in the MCP config:

---

$3

Create or edit mcp.json in your project root or ~/.config/opencode/mcp.json globally:

`json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@calltelemetry/linear-mcp"],
"env": {
"LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
}
}
}
}
`

---

$3

Create or edit .mcp.json in your project root:

`json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@calltelemetry/linear-mcp"],
"env": {
"LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
}
}
}
}
`

Or configure globally in ~/.claude/settings.json:

`json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@calltelemetry/linear-mcp"],
"env": {
"LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
}
}
}
}
`

---

$3

Edit the configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude Desktop\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

`json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@calltelemetry/linear-mcp"],
"env": {
"LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
}
}
}
}
`

---

$3

Edit the configuration file:

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

`json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@calltelemetry/linear-mcp"],
"env": {
"LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxx"
}
}
}
}
`

---

Available MCP Tools (50+ tools)

$3


| Tool | Description |
|------|-------------|
| create_issue | Create a new issue or subissue |
| update_issue | Update an existing issue |
| get_issue | Get issue details with optional relationships |
| search_issues | Search issues with advanced filters |
| delete_issue | Delete an issue |

$3

| Tool | Description |
|------|-------------|
| get_teams | List teams with optional filtering |

$3

| Tool | Description |
|------|-------------|
| get_users | List users in workspace or team |
| get_user | Get user details (use "me" for self) |
| get_team_members | List team members with roles |

$3

| Tool | Description |
|------|-------------|
| create_comment | Add a comment to an issue |

$3

| Tool | Description |
|------|-------------|
| get_projects | List projects with filtering |
| get_project_updates | Get project updates |
| create_project_update | Create a project update |

$3

| Tool | Description |
|------|-------------|
| get_milestones | List milestones (all or by project) |
| get_milestone | Get milestone details |
| create_milestone | Create a new milestone |
| update_milestone | Update a milestone |
| delete_milestone | Delete a milestone |

$3

| Tool | Description |
|------|-------------|
| get_initiatives | List initiatives |
| get_initiative | Get initiative details |
| create_initiative | Create a new initiative |
| update_initiative | Update an initiative |
| add_project_to_initiative | Link a project to an initiative |
| remove_project_from_initiative | Unlink a project |

$3

| Tool | Description |
|------|-------------|
| get_documents | List documents |
| get_document | Get document details |
| create_document | Create a new document |
| update_document | Update a document |

$3

| Tool | Description |
|------|-------------|
| get_cycles | List cycles for a team |
| get_cycle | Get cycle details |
| create_cycle | Create a new cycle |
| update_cycle | Update a cycle |

$3

| Tool | Description |
|------|-------------|
| get_workflow_states | List workflow states for a team |
| get_labels | List labels (workspace or team) |
| create_label | Create a new label |
| update_label | Update a label |

$3

| Tool | Description |
|------|-------------|
| get_attachments | List attachments for an issue |
| get_attachment | Get attachment details |
| create_attachment | Create an attachment on an issue |
| update_attachment | Update an attachment |
| delete_attachment | Delete an attachment |

$3

| Tool | Description |
|------|-------------|
| get_notifications | List notifications for current user |
| get_notification | Get notification details |
| mark_notification_read | Mark a notification as read |
| mark_all_notifications_read | Mark all notifications as read |
| archive_notification | Archive a notification |
| snooze_notification | Snooze until a specified time |
| unsnooze_notification | Unsnooze a notification |
| get_unread_notification_count | Get count of unread notifications |

$3

| Tool | Description |
|------|-------------|
| get_issue_history | Get change history for an issue |

Tool Input Schemas

$3

`json
{
"teamId": "string",
"title": "string",
"description": "string",
"parentId": "string",
"status": "string",
"priority": "number",
"assigneeId": "string | 'me'",
"labelIds": ["string"],
"projectId": "string",
"milestoneId": "string"
}
`

$3

`json
{
"query": "string",
"includeRelationships": "boolean",
"filter": {
"priority": { "gte": "number" },
"assignee": { "id": { "eq": "string" } },
"state": { "type": { "eq": "started" } },
"and": [{ }],
"or": [{ }]
},
"projectId": "string",
"projectName": "string"
}
`

$3

`json
{
"projectId": "string",
"name": "string",
"description": "string",
"targetDate": "string (ISO format)",
"sortOrder": "number"
}
`

$3

`json
{
"name": "string",
"description": "string",
"color": "string (hex)",
"icon": "string",
"sortOrder": "number",
"targetDate": "string (ISO format)"
}
`

$3

`json
{
"title": "string",
"projectId": "string",
"content": "string (markdown)",
"icon": "string",
"color": "string"
}
`

$3

`json
{
"teamId": "string",
"name": "string",
"description": "string",
"startsAt": "string (ISO format)",
"endsAt": "string (ISO format)"
}
``

Technical Details

* Built with TypeScript in strict mode
* Uses Linear's official SDK (@linear/sdk v70)
* Uses MCP SDK (@modelcontextprotocol/sdk)
* Authentication via API tokens
* Comprehensive error handling
* Vite build system
* ESM modules throughout
* Type-safe operations

Error Handling

The server implements comprehensive error handling:
* Network error detection
* HTTP status code handling
* Input validation for all parameters
* Safe error propagation through MCP protocol
* Rate limit detection and handling
* Authentication error handling

Version History

* v0.5.0 - Full SDK parity: attachments, notifications/inbox, issue history
* v0.4.0 - Major expansion with milestones, initiatives, documents, users, cycles, and labels
* v0.3.0 - Added project updates and health status
* v0.2.0 - Added cycle filtering and advanced search
* v0.1.0 - Initial release with basic issue operations

License

This project is licensed under the MIT License - see the LICENSE file for details.

Originally created by Dimosthenis Kaponis, expanded by CallTelemetry.