# API Reference
Complete reference for all MCP Linear.app server tools.
## Table of Contents
- [Issue Management](#issue-management)
- [Team & Workflow](#team--workflow)
- [Projects](#projects)
- [Cycles (Sprints)](#cycles-sprints)
- [Labels](#labels)
- [Users](#users)
- [Common Patterns](#common-patterns)
---
## Issue Management
### linear_list_issues
List Linear issues with optional filters.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ----------------------------------- |
| `teamId` | string | No | - | Filter by team ID |
| `projectId` | string | No | - | Filter by project ID |
| `assigneeId` | string | No | - | Filter by assignee user ID |
| `status` | enum | No | - | Filter by status (see values below) |
| `priority` | number | No | - | Filter by priority (0-4) |
| `label` | string | No | - | Filter by label name |
| `limit` | number | No | 25 | Maximum number of issues (1-100) |
| `includeArchived` | boolean | No | false | Include archived issues |
**Status values:**
- `backlog`
- `unstarted`
- `started`
- `completed`
- `canceled`
- `triage`
- `in_progress`
- `done`
**Priority values:**
- `0` - None
- `1` - Urgent
- `2` - High
- `3` - Medium
- `4` - Low
**Response:**
```json
{
"count": 10,
"issues": [
{
"id": "issue-id-123",
"identifier": "ENG-123",
"title": "Fix login bug",
"description": "Users can't log in with OAuth",
"priority": 1,
"priorityLabel": "Urgent",
"estimate": 5,
"url": "https://linear.app/team/issue/ENG-123",
"createdAt": "2024-01-15T10:30:00Z",
"updatedAt": "2024-01-16T14:20:00Z",
"dueDate": "2024-01-20",
"state": {
"id": "state-id",
"name": "In Progress",
"type": "started",
"color": "#f2c94c"
},
"assignee": {
"id": "user-id",
"name": "John Doe",
"email": "john@example.com"
},
"team": {
"id": "team-id",
"name": "Engineering",
"key": "ENG"
},
"project": {
"id": "project-id",
"name": "Authentication Revamp"
},
"labels": [
{
"id": "label-id",
"name": "bug",
"color": "#e5484d"
}
],
"parent": null
}
]
}
```
**Example usage:**
```
List all urgent issues in the Engineering team
List issues assigned to me with status started
List all bugs in project X
```
---
### linear_create_issue
Create a new Linear issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | -------------------------------------- |
| `title` | string | Yes | Issue title |
| `teamId` | string | Yes | Team ID where issue will be created |
| `description` | string | No | Issue description (markdown supported) |
| `projectId` | string | No | Project ID to assign to |
| `assigneeId` | string | No | User ID to assign to |
| `priority` | number | No | Priority (0-4) |
| `labelIds` | string[] | No | Array of label IDs |
| `stateId` | string | No | Workflow state ID |
| `estimate` | number | No | Estimate in points |
| `dueDate` | string | No | Due date (YYYY-MM-DD) |
| `parentId` | string | No | Parent issue ID (for sub-issues) |
| `cycleId` | string | No | Cycle ID to assign the issue to |
**Response:**
```json
{
"success": true,
"message": "Issue created: ENG-124 - Implement OAuth",
"issue": {
// ... full issue object
}
}
```
**Example usage:**
```
Create an issue titled "Implement OAuth" in the Engineering team with high priority
Create a bug report in team X about login issues
```
---
### linear_update_issue
Update an existing Linear issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | -------------------------------------------- |
| `issueId` | string | Yes | Issue ID or identifier (e.g., "ENG-123") |
| `title` | string | No | New title |
| `description` | string | No | New description |
| `assigneeId` | string | No | New assignee user ID |
| `priority` | number | No | New priority (0-4) |
| `stateId` | string | No | New workflow state ID |
| `labelIds` | string[] | No | New label IDs (replaces existing) |
| `estimate` | number | No | New estimate |
| `dueDate` | string | No | New due date (YYYY-MM-DD) |
| `projectId` | string | No | New project ID |
| `cycleId` | string | No | New cycle ID (use null to remove from cycle) |
**Response:**
```json
{
"success": true,
"message": "Issue updated: ENG-123",
"issue": {
// ... full issue object
}
}
```
**Example usage:**
```
Update issue ENG-123 to change priority to urgent
Change the assignee of ENG-45 to John
Move issue ENG-100 to the "In Review" state
```
---
### linear_get_issue
Get detailed information about a specific issue.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ---------------------------------------- |
| `issueId` | string | Yes | Issue ID or identifier (e.g., "ENG-123") |
**Response:**
```json
{
// ... full issue object (same as in list_issues)
}
```
**Example usage:**
```
Get details for issue ENG-123
Show me the full information about issue DESIGN-45
```
---
### linear_search_issues
Search issues by text query.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ----------------------- |
| `query` | string | Yes | - | Search query text |
| `teamId` | string | No | - | Limit to specific team |
| `limit` | number | No | 25 | Maximum results (1-100) |
| `includeArchived` | boolean | No | false | Include archived issues |
**Response:**
```json
{
"query": "authentication",
"count": 5,
"issues": [
// ... array of issue objects
]
}
```
**Example usage:**
```
Search for issues about authentication
Find all issues mentioning "database migration"
```
---
### linear_assign_issue
Assign an issue to a user.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ---------------------- |
| `issueId` | string | Yes | Issue ID or identifier |
| `assigneeId` | string | Yes | User ID to assign to |
**Response:**
```json
{
"success": true,
"message": "Issue ENG-123 assigned to John Doe",
"issue": {
// ... full issue object
}
}
```
**Example usage:**
```
Assign issue ENG-123 to user abc-123
Assign this issue to John
```
---
### linear_add_comment
Add a comment to an issue.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | --------------------------------- |
| `issueId` | string | Yes | Issue ID or identifier |
| `body` | string | Yes | Comment body (markdown supported) |
**Response:**
```json
{
"success": true,
"message": "Comment added successfully",
"comment": {
"id": "comment-id",
"body": "This is fixed in the latest build",
"createdAt": "2024-01-16T15:30:00Z"
}
}
```
**Example usage:**
```
Add a comment to ENG-123 saying "This is fixed"
Comment on this issue that testing is complete
```
---
## Team & Workflow
### linear_list_teams
List all teams in your workspace.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ---------------------- |
| `includeArchived` | boolean | No | false | Include archived teams |
**Response:**
```json
{
"count": 3,
"teams": [
{
"id": "team-id",
"name": "Engineering",
"key": "ENG",
"description": "Product engineering team"
}
]
}
```
**Example usage:**
```
List all teams
Show me all active teams
```
---
### linear_get_team
Get detailed information about a specific Linear team by ID.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------ |
| `teamId` | string | Yes | Team ID (required) |
**Response:**
```json
{
"id": "team-id",
"name": "Engineering",
"key": "ENG",
"description": "Product engineering team",
"icon": "⚙️",
"color": "#3b82f6",
"timezone": "America/Los_Angeles",
"private": false,
"createdAt": "2023-01-15T10:00:00Z",
"updatedAt": "2024-01-20T14:30:00Z",
"archivedAt": null
}
```
**Example usage:**
```
Get details for team abc-123
Show me information about the Engineering team
```
---
### linear_create_team
Create a new Linear team. Requires a unique name and key.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------------------------- |
| `name` | string | Yes | Team name (required) |
| `key` | string | Yes | Team key - 1-5 uppercase letters (e.g., "ENG") |
| `description` | string | No | Team description |
| `icon` | string | No | Team icon (emoji) |
| `color` | string | No | Team color in hex format (e.g., "#FF0000") |
| `timezone` | string | No | Team timezone (e.g., "America/Los_Angeles") |
| `private` | boolean | No | Whether the team is private |
**Response:**
```json
{
"success": true,
"message": "Team created: ENG - Engineering",
"team": {
"id": "team-id",
"name": "Engineering",
"key": "ENG",
"description": "Product engineering team",
"icon": "⚙️",
"color": "#3b82f6",
"timezone": "America/Los_Angeles",
"private": false,
"createdAt": "2024-01-31T10:00:00Z",
"updatedAt": "2024-01-31T10:00:00Z",
"archivedAt": null
}
}
```
**Example usage:**
```
Create a team called "Engineering" with key "ENG"
Create a new Design team with key "DES" and blue color
```
---
### linear_update_team
Update an existing Linear team. You can update any team property.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ------------------ |
| `teamId` | string | Yes | Team ID (required) |
| `name` | string | No | New team name |
| `key` | string | No | New team key |
| `description` | string | No | New description |
| `icon` | string | No | New team icon |
| `color` | string | No | New team color |
| `timezone` | string | No | New team timezone |
| `private` | boolean | No | Privacy setting |
**Response:**
```json
{
"success": true,
"message": "Team updated: ENG - Engineering",
"team": {
"id": "team-id",
"name": "Engineering",
"key": "ENG",
"description": "Updated description",
"icon": "🚀",
"color": "#ef4444",
"timezone": "America/New_York",
"private": false,
"createdAt": "2024-01-31T10:00:00Z",
"updatedAt": "2024-02-01T15:30:00Z",
"archivedAt": null
}
}
```
**Example usage:**
```
Update team abc-123 to change the description
Change the icon for the Engineering team to a rocket
```
---
### linear_list_workflow_states
List workflow states for a team.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------- |
| `teamId` | string | Yes | Team ID |
**Response:**
```json
{
"count": 5,
"states": [
{
"id": "state-id",
"name": "Backlog",
"type": "backlog",
"color": "#bec2c8",
"description": "Work that has been planned",
"position": 0
}
]
}
```
**Example usage:**
```
List workflow states for the Engineering team
Show me all states for team abc-123
```
---
## Projects
### linear_list_projects
List all projects.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ------------------------- |
| `teamId` | string | No | - | Filter by team ID |
| `includeArchived` | boolean | No | false | Include archived projects |
**Response:**
```json
{
"count": 5,
"projects": [
{
"id": "project-id",
"name": "Authentication Revamp",
"description": "Redesign authentication system",
"state": "started",
"progress": 0.45,
"priority": 2,
"color": "#3b82f6",
"icon": "🚀",
"startDate": "2024-01-01",
"targetDate": "2024-03-31",
"url": "https://linear.app/team/project/auth-revamp",
"createdAt": "2023-12-15T10:00:00Z",
"updatedAt": "2024-01-15T14:30:00Z",
"lead": {
"id": "user-id",
"name": "Jane Smith",
"email": "jane@example.com"
},
"teams": [
{
"id": "team-id",
"name": "Engineering",
"key": "ENG"
}
]
}
]
}
```
**Example usage:**
```
List all projects
List projects for the Engineering team
```
---
### linear_create_project
Create a new Linear project.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ---------------------------------------------------- |
| `name` | string | Yes | Project name |
| `teamIds` | string[] | Yes | Array of team IDs this project is associated with |
| `description` | string | No | Project description |
| `leadId` | string | No | User ID of the project lead |
| `memberIds` | string[] | No | Array of user IDs for project members |
| `color` | string | No | Project color in hex format (e.g., "#FF0000") |
| `icon` | string | No | Project icon (emoji or icon name) |
| `priority` | number | No | Priority (0=None, 1=Urgent, 2=High, 3=Normal, 4=Low) |
| `startDate` | string | No | Planned start date (YYYY-MM-DD) |
| `targetDate` | string | No | Planned target/completion date (YYYY-MM-DD) |
| `statusId` | string | No | Project status ID |
| `content` | string | No | Project content in markdown format |
**Response:**
```json
{
"id": "project-id",
"name": "Website Redesign",
"description": "Complete redesign of company website",
"state": "planned",
"progress": 0,
"priority": 2,
"color": "#3b82f6",
"icon": "🎨",
"startDate": "2024-02-01",
"targetDate": "2024-03-31",
"url": "https://linear.app/team/project/website-redesign",
"createdAt": "2024-01-31T10:00:00Z",
"updatedAt": "2024-01-31T10:00:00Z",
"lead": {
"id": "user-id",
"name": "Alice Johnson",
"email": "alice@example.com"
},
"teams": [
{
"id": "design-team-id",
"name": "Design",
"key": "DES"
},
{
"id": "eng-team-id",
"name": "Engineering",
"key": "ENG"
}
]
}
```
**Example usage:**
```
Create a project called "Website Redesign" for the Design and Engineering teams
Create a new project "Mobile App v2" with target date of end of Q2 and assign Jane as lead
```
---
### linear_update_project
Update an existing Linear project.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ----------------------------------------------- |
| `projectId` | string | Yes | Project ID |
| `name` | string | No | New project name |
| `description` | string | No | New project description |
| `leadId` | string | No | New project lead user ID |
| `memberIds` | string[] | No | New project member user IDs (replaces existing) |
| `color` | string | No | New project color |
| `icon` | string | No | New project icon |
| `priority` | number | No | New priority (0-4) |
| `startDate` | string | No | New start date (YYYY-MM-DD) |
| `targetDate` | string | No | New target date (YYYY-MM-DD) |
| `statusId` | string | No | New project status ID |
| `content` | string | No | New project content in markdown |
| `teamIds` | string[] | No | New team IDs (replaces existing) |
| `state` | enum | No | Project state (see values below) |
**State values:**
- `planned`
- `started`
- `paused`
- `completed`
- `canceled`
**Response:**
```json
{
"id": "project-id",
"name": "Website Redesign",
"description": "Complete redesign of company website - Updated scope",
"state": "started",
"progress": 0.25,
"priority": 1,
"color": "#ef4444",
"icon": "🚀",
"startDate": "2024-02-01",
"targetDate": "2024-04-15",
"url": "https://linear.app/team/project/website-redesign",
"createdAt": "2024-01-31T10:00:00Z",
"updatedAt": "2024-02-05T14:30:00Z",
"lead": {
"id": "user-id",
"name": "Alice Johnson",
"email": "alice@example.com"
},
"teams": [
{
"id": "design-team-id",
"name": "Design",
"key": "DES"
},
{
"id": "eng-team-id",
"name": "Engineering",
"key": "ENG"
}
]
}
```
**Example usage:**
```
Update project abc-123 to mark it as completed
Change the target date of project abc-123 to end of March
Update project abc-123 to change priority to urgent and assign Bob as lead
```
---
### linear_get_project
Get detailed information about a specific Linear project.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `projectId` | string | Yes | Project ID |
**Response:**
```json
{
"id": "project-id",
"name": "Website Redesign",
"description": "Complete redesign of company website",
"state": "started",
"progress": 0.35,
"priority": 2,
"color": "#3b82f6",
"icon": "🎨",
"startDate": "2024-02-01",
"targetDate": "2024-03-31",
"url": "https://linear.app/team/project/website-redesign",
"createdAt": "2024-01-31T10:00:00Z",
"updatedAt": "2024-02-10T16:20:00Z",
"lead": {
"id": "user-id",
"name": "Alice Johnson",
"email": "alice@example.com"
},
"teams": [
{
"id": "design-team-id",
"name": "Design",
"key": "DES"
},
{
"id": "eng-team-id",
"name": "Engineering",
"key": "ENG"
}
]
}
```
**Example usage:**
```
Get details for project abc-123
Show me the full information for the Website Redesign project
```
---
### linear_archive_project
Archive a Linear project. Archived projects are hidden from active views but can be restored.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | --------------------- |
| `projectId` | string | Yes | Project ID to archive |
**Response:**
```json
{
"success": true,
"message": "Project archived successfully"
}
```
**Example usage:**
```
Archive project abc-123
Archive the completed Website Redesign project
```
---
### linear_unarchive_project
Unarchive a previously archived Linear project, restoring it to active status.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ----------------------- |
| `projectId` | string | Yes | Project ID to unarchive |
**Response:**
```json
{
"success": true,
"message": "Project unarchived successfully"
}
```
**Example usage:**
```
Unarchive project abc-123
Restore the Mobile App v2 project from archive
```
---
## Cycles (Sprints)
### linear_create_cycle
Create a new cycle (sprint).
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ----------------------- |
| `teamId` | string | Yes | Team ID |
| `name` | string | Yes | Cycle name |
| `description` | string | No | Cycle description |
| `startsAt` | string | Yes | Start date (YYYY-MM-DD) |
| `endsAt` | string | Yes | End date (YYYY-MM-DD) |
**Response:**
```json
{
"success": true,
"message": "Cycle created: Sprint 12",
"cycle": {
"id": "cycle-id",
"number": 12,
"name": "Sprint 12",
"description": "Q1 Sprint 12",
"startsAt": "2024-02-01T00:00:00Z",
"endsAt": "2024-02-14T23:59:59Z",
"progress": 0,
"team": {
"id": "team-id",
"name": "Engineering",
"key": "ENG"
}
}
}
```
**Example usage:**
```
Create a 2-week sprint starting today for Engineering
Create a cycle named "Sprint 12" for team X from Feb 1 to Feb 14
```
---
### linear_list_cycles
List cycles for a team.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ----------------------- |
| `teamId` | string | Yes | - | Team ID |
| `includeArchived` | boolean | No | false | Include archived cycles |
**Response:**
```json
{
"count": 3,
"cycles": [
{
"id": "cycle-id",
"number": 12,
"name": "Sprint 12",
"startsAt": "2024-02-01T00:00:00Z",
"endsAt": "2024-02-14T23:59:59Z",
"progress": 0.6,
"team": {
"id": "team-id",
"name": "Engineering",
"key": "ENG"
}
}
]
}
```
**Example usage:**
```
List all cycles for the Engineering team
Show me active sprints for team X
```
---
### linear_get_cycle
Get detailed information about a specific cycle by ID.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------- |
| `cycleId` | string | Yes | Cycle ID (required) |
**Response:**
```json
{
"id": "cycle-id",
"number": 12,
"name": "Sprint 12",
"description": "Q1 Sprint 12",
"startsAt": "2024-02-01T00:00:00Z",
"endsAt": "2024-02-14T23:59:59Z",
"progress": 0.45,
"team": {
"id": "team-id",
"name": "Engineering",
"key": "ENG"
}
}
```
**Example usage:**
```
Get details for cycle abc-123
Show me the information for Sprint 12
```
---
### linear_update_cycle
Update an existing cycle. You can update the name, description, start date, and end date.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | --------------------------------- |
| `cycleId` | string | Yes | Cycle ID (required) |
| `name` | string | No | New cycle name |
| `description` | string | No | New cycle description |
| `startsAt` | string | No | New start date in ISO 8601 format |
| `endsAt` | string | No | New end date in ISO 8601 format |
**Response:**
```json
{
"success": true,
"message": "Cycle updated: Sprint 12 Extended",
"cycle": {
"id": "cycle-id",
"number": 12,
"name": "Sprint 12 Extended",
"description": "Q1 Sprint 12 - Extended deadline",
"startsAt": "2024-02-01T00:00:00Z",
"endsAt": "2024-02-21T23:59:59Z",
"progress": 0.45,
"team": {
"id": "team-id",
"name": "Engineering",
"key": "ENG"
}
}
}
```
**Example usage:**
```
Update cycle abc-123 to extend the end date by one week
Change the name of cycle abc-123 to "Sprint 13"
```
---
### linear_archive_cycle
Archive a cycle. Archived cycles are hidden from active views but can be restored.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------ |
| `cycleId` | string | Yes | Cycle ID to archive (required) |
**Response:**
```json
{
"success": true,
"message": "Cycle archived successfully"
}
```
**Example usage:**
```
Archive cycle abc-123
Archive the completed Sprint 12
```
---
### linear_unarchive_cycle
Unarchive a previously archived cycle, restoring it to active status.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------------------------- |
| `cycleId` | string | Yes | Cycle ID to unarchive (required) |
**Response:**
```json
{
"success": true,
"message": "Cycle unarchived successfully"
}
```
**Example usage:**
```
Unarchive cycle abc-123
Restore Sprint 11 from archive
```
---
## Custom Views
### linear_list_custom_views
List all custom views. Custom views are saved filters that allow you to organize and view issues in specific ways.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ----------------------------- |
| `includeArchived` | boolean | No | false | Include archived custom views |
**Response:**
```json
{
"count": 2,
"views": [
{
"id": "view-id",
"name": "My High Priority Issues",
"description": "All urgent and high priority issues assigned to me",
"icon": "🔥",
"color": "#ef4444",
"shared": false,
"createdAt": "2024-01-20T10:00:00Z",
"updatedAt": "2024-01-25T14:30:00Z",
"owner": {
"id": "user-id",
"name": "John Doe",
"email": "john@example.com"
},
"team": {
"id": "team-id",
"name": "Engineering",
"key": "ENG"
}
}
]
}
```
**Example usage:**
```
List all custom views
Show me all my saved views
```
---
### linear_create_custom_view
Create a new custom view with filters. Custom views allow you to save filtered issue lists for quick access.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ----------------------------------------------- |
| `name` | string | Yes | Custom view name |
| `description` | string | No | Custom view description |
| `teamId` | string | No | Team ID to associate the view with |
| `projectId` | string | No | Project ID to associate the view with |
| `icon` | string | No | View icon (emoji or icon name) |
| `color` | string | No | View icon color in hex format (e.g., "#FF0000") |
| `shared` | boolean | No | Whether the view is shared with everyone |
| `filters` | object | No | JSON object containing issue filters |
**Filter Examples:**
```json
{
"priority": { "eq": 1 },
"assignee": { "id": { "eq": "user-id" } },
"state": { "type": { "eq": "started" } }
}
```
**Response:**
```json
{
"id": "view-id",
"name": "My High Priority Issues",
"description": "All urgent and high priority issues assigned to me",
"icon": "🔥",
"color": "#ef4444",
"shared": false,
"filters": {
"priority": { "eq": 1 },
"assignee": { "id": { "eq": "user-id" } },
"state": { "type": { "eq": "started" } }
},
"createdAt": "2024-01-31T10:00:00Z",
"updatedAt": "2024-01-31T10:00:00Z",
"owner": {
"id": "user-id",
"name": "John Doe",
"email": "john@example.com"
},
"team": null
}
```
**Example usage:**
```
Create a custom view called "My Urgent Bugs" that shows only urgent priority bugs assigned to me
Create a shared view for the team showing all in-progress issues
```
**See also:** [Custom View Filters Guide](./CUSTOM_VIEW_FILTERS.md) for detailed filter documentation
---
### linear_update_custom_view
Update an existing custom view. You can change the name, description, filters, sharing settings, and more.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------------------- |
| `viewId` | string | Yes | Custom view ID |
| `name` | string | No | New view name |
| `description` | string | No | New view description |
| `teamId` | string | No | New team ID |
| `projectId` | string | No | New project ID |
| `icon` | string | No | New view icon |
| `color` | string | No | New view icon color |
| `shared` | boolean | No | Whether the view is shared |
| `filters` | object | No | New JSON object containing issue filters |
**Response:**
```json
{
"id": "view-id",
"name": "Updated View Name",
"description": "Updated description",
"icon": "✨",
"color": "#3b82f6",
"shared": true,
"filters": {
"priority": { "eq": 2 },
"state": { "type": { "eq": "started" } }
},
"createdAt": "2024-01-31T10:00:00Z",
"updatedAt": "2024-02-01T15:30:00Z",
"owner": {
"id": "user-id",
"name": "John Doe",
"email": "john@example.com"
},
"team": {
"id": "team-id",
"name": "Engineering",
"key": "ENG"
}
}
```
**Example usage:**
```
Update custom view abc-123 to make it shared with the team
Change the filters on view abc-123 to show only high priority issues
```
---
### linear_get_custom_view
Get detailed information about a specific custom view by ID, including its filters.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | -------------- |
| `viewId` | string | Yes | Custom view ID |
**Response:**
```json
{
"id": "view-id",
"name": "My High Priority Issues",
"description": "All urgent and high priority issues assigned to me",
"icon": "🔥",
"color": "#ef4444",
"shared": false,
"filters": {
"priority": { "eq": 1 },
"assignee": { "id": { "eq": "user-id" } }
},
"createdAt": "2024-01-31T10:00:00Z",
"updatedAt": "2024-01-31T10:00:00Z",
"owner": {
"id": "user-id",
"name": "John Doe",
"email": "john@example.com"
},
"team": null
}
```
**Example usage:**
```
Get details for custom view abc-123
Show me the configuration for my priority view
```
---
### linear_delete_custom_view
Delete a custom view. This action cannot be undone.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------ |
| `viewId` | string | Yes | Custom view ID to delete |
**Response:**
```json
{
"success": true,
"message": "Custom view deleted successfully"
}
```
**Example usage:**
```
Delete custom view abc-123
Remove the old sprint view
```
---
## Labels
### linear_create_label
Create a new label.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------- |
| `name` | string | Yes | Label name |
| `teamId` | string | Yes | Team ID |
| `color` | string | No | Color in hex format (e.g., "#FF0000") |
| `description` | string | No | Label description |
**Response:**
```json
{
"success": true,
"message": "Label created: bug",
"label": {
"id": "label-id",
"name": "bug",
"color": "#e5484d",
"description": "Something isn't working"
}
}
```
**Example usage:**
```
Create a label called "bug" with red color for Engineering
Create a "feature" label for team X
```
---
### linear_list_labels
List all labels.
**Parameters:**
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------- |
| `teamId` | string | No | Filter by team ID |
**Response:**
```json
{
"count": 10,
"labels": [
{
"id": "label-id",
"name": "bug",
"color": "#e5484d",
"description": "Something isn't working"
}
]
}
```
**Example usage:**
```
List all labels
List labels for the Engineering team
```
---
## Users
### linear_list_users
List all users in your workspace.
**Parameters:**
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ---------------------- |
| `includeDisabled` | boolean | No | false | Include disabled users |
**Response:**
```json
{
"count": 15,
"users": [
{
"id": "user-id",
"name": "John Doe",
"email": "john@example.com",
"displayName": "John",
"active": true,
"admin": false
}
]
}
```
**Example usage:**
```
List all users
Show me all active team members
```
---
## Common Patterns
### Getting IDs for Operations
Many operations require IDs (team, user, project, etc.). Use list operations first:
```
1. List all teams
2. Note the team ID
3. Create an issue using that team ID
```
### Issue Identifiers
Issues can be referenced by:
- Full ID: `"issue-abc-123-def"`
- Identifier: `"ENG-123"` (team key + number)
The identifier format is more human-friendly and is recommended.
### Date Formats
Dates should be in ISO 8601 format:
- Date only: `"2024-01-31"`
- Date and time: `"2024-01-31T15:30:00Z"`
### Markdown Support
The following fields support markdown:
- Issue descriptions
- Comment bodies
- Project descriptions
- Cycle descriptions
### Filtering Best Practices
1. Use specific filters to reduce API load
2. Combine filters to narrow results
3. Use `limit` parameter to control result size
4. Consider pagination for large datasets
### Error Handling
All tools return clear error messages:
- Missing required parameters
- Invalid IDs
- Permission errors
- API rate limits
- Network errors
Example error response:
```json
{
"error": "Failed to create issue: Team not found"
}
```
