Linear MCP connector

1. Install the SDK

   Node.js

   npm install @scalekit-sdk/node

   Python

   pip install scalekit

   Full SDK reference: Node.js | Python

2. Set your credentials

   Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

   .env

   SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
   SCALEKIT_CLIENT_ID=<your-client-id>
   SCALEKIT_CLIENT_SECRET=<your-client-secret>

3. Authorize and make your first call

   Node.js

   quickstart.ts

   import { ScalekitClient } from '@scalekit-sdk/node'
   import 'dotenv/config'
   
   const scalekit = new ScalekitClient(
     process.env.SCALEKIT_ENV_URL,
     process.env.SCALEKIT_CLIENT_ID,
     process.env.SCALEKIT_CLIENT_SECRET,
   )
   const actions = scalekit.actions
   
   const connector = 'linearmcp'
   const identifier = 'user_123'
   
   // Generate an authorization link for the user
   const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
   console.log('Authorize Linear MCP:', link)
   process.stdout.write('Press Enter after authorizing...')
   await new Promise(r => process.stdin.once('data', r))
   
   // Make your first call
   const result = await actions.executeTool({
     connector,
     identifier,
     toolName: 'linearmcp_list_comments',
     toolInput: {},
   })
   console.log(result)

   Python

   quickstart.py

   import os
   from scalekit.client import ScalekitClient
   from dotenv import load_dotenv
   load_dotenv()
   
   scalekit_client = ScalekitClient(
       env_url=os.getenv("SCALEKIT_ENV_URL"),
       client_id=os.getenv("SCALEKIT_CLIENT_ID"),
       client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),
   )
   actions = scalekit_client.actions
   
   connection_name = "linearmcp"
   identifier = "user_123"
   
   # Generate an authorization link for the user
   link_response = actions.get_authorization_link(
       connection_name=connection_name,
       identifier=identifier,
   )
   print("Authorize Linear MCP:", link_response.link)
   input("Press Enter after authorizing...")
   
   # Make your first call
   result = actions.execute_tool(
       tool_input={},
       tool_name="linearmcp_list_comments",
       connection_name=connection_name,
       identifier=identifier,
   )
   print(result)

What you can do

Connect this agent connector to let your agent:

• Search documentation — Search Linear’s documentation to learn about features and usage
• Update save status — Create or update a project/initiative status update
• Project save — Create or update a Linear project
• Milestone save — Create or update a milestone in a Linear project
• Issue save — Create or update a Linear issue
• Document save — Create or update a Linear document

Tool list

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

linearmcp_create_attachment#Deprecated fallback for tiny files only. Accepts base64 file content and uploads it through the MCP worker. Prefer prepare_attachment_upload plus direct PUT plus create_attachment_from_upload.6 params▾

Deprecated fallback for tiny files only. Accepts base64 file content and uploads it through the MCP worker. Prefer prepare_attachment_upload plus direct PUT plus create_attachment_from_upload.

NameTypeRequiredDescription

base64ContentstringrequiredDeprecated base64-encoded file content to upload

contentTypestringrequiredMIME type for the upload (e.g., 'image/png', 'application/pdf')

filenamestringrequiredFilename for the upload (e.g., 'screenshot.png')

issuestringrequiredIssue ID or identifier (e.g., LIN-123)

subtitlestringoptionalOptional subtitle for the attachment

titlestringoptionalOptional title for the attachment

linearmcp_create_attachment_from_upload#Link an already-uploaded Linear assetUrl to an existing issue as an attachment.4 params▾

Link an already-uploaded Linear assetUrl to an existing issue as an attachment.

NameTypeRequiredDescription

assetUrlstringrequiredLinear upload assetUrl returned by prepare_attachment_upload

issuestringrequiredIssue ID or identifier (e.g., LIN-123)

subtitlestringoptionalOptional attachment subtitle

titlestringoptionalAttachment title. Defaults to filename or asset URL

linearmcp_create_issue_label#Create a new Linear issue label6 params▾

Create a new Linear issue label

NameTypeRequiredDescription

namestringrequiredLabel name

colorstringoptionalHex color code for the label

descriptionstringoptionalLabel description

isGroupbooleanoptionalWhether this label is a group (container for other labels)

parentstringoptionalParent label group name

teamIdstringoptionalTeam UUID to scope the label. Omit for workspace-level label.

linearmcp_delete_attachment#Delete an attachment by ID1 param▾

Delete an attachment by ID

NameTypeRequiredDescription

idstringrequiredAttachment ID

linearmcp_delete_comment#Delete a Linear comment.1 param▾

Delete a Linear comment.

NameTypeRequiredDescription

idstringrequiredComment ID

linearmcp_delete_status_update#Delete (archive) a project or initiative status update.2 params▾

Delete (archive) a project or initiative status update.

NameTypeRequiredDescription

idstringrequiredStatus update ID to delete

typestringrequiredType of status update — project or initiative

linearmcp_extract_images#Extract and fetch images from markdown content. Use this to view screenshots, diagrams, or other images embedded in Linear issues, comments, or documents.1 param▾

Extract and fetch images from markdown content. Use this to view screenshots, diagrams, or other images embedded in Linear issues, comments, or documents.

NameTypeRequiredDescription

markdownstringrequiredMarkdown content containing image references

linearmcp_get_attachment#Retrieve an attachment's content by ID.1 param▾

Retrieve an attachment's content by ID.

NameTypeRequiredDescription

idstringrequiredAttachment ID

linearmcp_get_diff#Exact lookup for a Linear diff. Use with review URLs, GitHub PR URLs, Linear full identifiers, UUIDs, or slugs.1 param▾

Exact lookup for a Linear diff. Use with review URLs, GitHub PR URLs, Linear full identifiers, UUIDs, or slugs.

NameTypeRequiredDescription

urlOrIdstringrequiredLinear review URL, diff slug, pull request ID, Linear full identifier, or GitHub PR URL

linearmcp_get_diff_threads#Exact lookup for diff threads. Use with review URLs, GitHub PR URLs, Linear full identifiers, UUIDs, or slugs.4 params▾

Exact lookup for diff threads. Use with review URLs, GitHub PR URLs, Linear full identifiers, UUIDs, or slugs.

NameTypeRequiredDescription

urlOrIdstringrequiredLinear review URL, diff slug, pull request ID, Linear full identifier, or GitHub PR URL

orderBystringoptionalSort: createdAt | updatedAt

resolvedbooleanoptionalFilter returned threads by resolved state

threadIdstringoptionalOptional top-level thread/comment ID to return

linearmcp_get_document#Retrieve a Linear document by ID or slug1 param▾

Retrieve a Linear document by ID or slug

NameTypeRequiredDescription

idstringrequiredDocument ID or slug

linearmcp_get_issue#Retrieve detailed information about an issue by ID, including attachments and git branch name4 params▾

Retrieve detailed information about an issue by ID, including attachments and git branch name

NameTypeRequiredDescription

idstringrequiredIssue ID or identifier (e.g., LIN-123)

includeCustomerNeedsbooleanoptionalInclude associated customer needs

includeRelationsbooleanoptionalInclude blocking/related/duplicate relations

includeReleasesbooleanoptionalInclude associated releases

linearmcp_get_issue_status#Retrieve detailed information about an issue status in Linear by name or ID3 params▾

Retrieve detailed information about an issue status in Linear by name or ID

NameTypeRequiredDescription

idstringrequiredStatus ID

namestringrequiredStatus name

teamstringrequiredTeam name or ID

linearmcp_get_milestone#Retrieve details of a specific milestone by ID or name2 params▾

Retrieve details of a specific milestone by ID or name

NameTypeRequiredDescription

projectstringrequiredProject name, ID, or slug

querystringrequiredMilestone name or ID

linearmcp_get_project#Retrieve details of a specific project in Linear4 params▾

Retrieve details of a specific project in Linear

NameTypeRequiredDescription

querystringrequiredProject name, ID, or slug

includeMembersbooleanoptionalInclude members in the response

includeMilestonesbooleanoptionalInclude milestones in the response

includeResourcesbooleanoptionalInclude resources (documents, links, attachments)

linearmcp_get_status_updates#List or get project/initiative status updates. Pass id to get a specific update, or filter to list.11 params▾

List or get project/initiative status updates. Pass id to get a specific update, or filter to list.

NameTypeRequiredDescription

typestringrequiredType of status update — project or initiative

createdAtstringoptionalReturn updates created after this ISO-8601 duration (e.g. P7D for last 7 days)

cursorstringoptionalPagination cursor from the previous response

idstringoptionalStatus update ID — returns the specific update if provided

includeArchivedbooleanoptionalInclude archived status updates

initiativestringoptionalInitiative name or ID to filter by

limitnumberoptionalMaximum number of status updates to return

orderBystringoptionalField to order results by

projectstringoptionalProject name, ID, or slug to filter by

updatedAtstringoptionalReturn updates modified after this ISO-8601 duration (e.g. P7D for last 7 days)

userstringoptionalUser ID, name, email, or 'me' to filter by author

linearmcp_get_team#Retrieve details of a specific Linear team1 param▾

Retrieve details of a specific Linear team

NameTypeRequiredDescription

querystringrequiredTeam UUID, key, or name

linearmcp_get_user#Retrieve details of a specific Linear user1 param▾

Retrieve details of a specific Linear user

NameTypeRequiredDescription

querystringrequiredUser ID, name, email, or 'me' for the authenticated user

linearmcp_list_comments#List comments on a Linear issue, project, initiative, document, or project milestone. Provide exactly one of issueId, projectId, initiativeId, documentId, or milestoneId.8 params▾

List comments on a Linear issue, project, initiative, document, or project milestone. Provide exactly one of issueId, projectId, initiativeId, documentId, or milestoneId.

NameTypeRequiredDescription

cursorstringoptionalNext page cursor

documentIdstringoptionalDocument ID or slug (provide exactly one parent)

initiativeIdstringoptionalInitiative name or ID (provide exactly one parent)

issueIdstringoptionalIssue ID or identifier (e.g., LIN-123) (provide exactly one parent)

limitnumberoptionalMax results (default 50, max 250)

milestoneIdstringoptionalMilestone UUID (provide exactly one parent)

orderBystringoptionalSort: createdAt | updatedAt

projectIdstringoptionalProject name, ID, or slug (provide exactly one parent)

linearmcp_list_cycles#Retrieve cycles for a specific Linear team2 params▾

Retrieve cycles for a specific Linear team

NameTypeRequiredDescription

teamIdstringrequiredTeam ID

typestringoptionalFilter: current, previous, next, or all

linearmcp_list_diffs#List Linear diff pull requests visible to the authenticated user7 params▾

List Linear diff pull requests visible to the authenticated user

NameTypeRequiredDescription

cursorstringoptionalNext page cursor

limitnumberoptionalMax results (default 50, max 250)

orderBystringoptionalSort: createdAt | updatedAt

ownerstringoptionalFilter by repository owner

querystringoptionalBroad search by title, branch, PR number, or bare slug

repostringoptionalFilter by repository name

statusstringoptionalFilter by pull request status

linearmcp_list_documents#List documents in the user's Linear workspace11 params▾

List documents in the user's Linear workspace

NameTypeRequiredDescription

createdAtstringoptionalCreated after: ISO-8601 date/duration (e.g., -P1D)

creatorIdstringoptionalFilter by creator user ID

cursorstringoptionalNext page cursor

includeArchivedbooleanoptionalInclude archived documents

initiativeIdstringoptionalFilter by initiative ID

limitnumberoptionalMax results (default 50, max 250)

orderBystringoptionalSort: createdAt | updatedAt

projectIdstringoptionalFilter by project ID

querystringoptionalSearch document title or content

teamIdstringoptionalFilter by team ID

updatedAtstringoptionalUpdated after: ISO-8601 date/duration (e.g., -P1D)

linearmcp_list_issue_labels#List available issue labels in a Linear workspace or team5 params▾

List available issue labels in a Linear workspace or team

NameTypeRequiredDescription

cursorstringoptionalNext page cursor

limitnumberoptionalMax results (default 50, max 250)

namestringoptionalFilter labels by name

orderBystringoptionalSort: createdAt | updatedAt

teamstringoptionalTeam name or ID

linearmcp_list_issue_statuses#List available issue statuses in a Linear team1 param▾

List available issue statuses in a Linear team

NameTypeRequiredDescription

teamstringrequiredTeam name or ID

linearmcp_list_issues#List issues in the user's Linear workspace. For my issues, use "me" as the assignee. Use "null" for no assignee.16 params▾

List issues in the user's Linear workspace. For my issues, use "me" as the assignee. Use "null" for no assignee.

NameTypeRequiredDescription

assigneestringoptionalUser ID, name, email, or "me"

createdAtstringoptionalCreated after: ISO-8601 date/duration (e.g., -P1D)

cursorstringoptionalNext page cursor

cyclestringoptionalCycle name, number, or ID

delegatestringoptionalAgent name or ID

includeArchivedbooleanoptionalInclude archived items

labelstringoptionalLabel name or ID

limitnumberoptionalMax results (default 50, max 250)

orderBystringoptionalSort: createdAt | updatedAt

parentIdstringoptionalParent issue ID or identifier (e.g., LIN-123)

prioritynumberoptional0=None, 1=Urgent, 2=High, 3=Medium, 4=Low

projectstringoptionalProject name, ID, or slug

querystringoptionalSearch issue title or description

statestringoptionalState type, name, or ID

teamstringoptionalTeam name or ID

updatedAtstringoptionalUpdated after: ISO-8601 date/duration (e.g., -P1D)

linearmcp_list_milestones#List all milestones in a Linear project1 param▾

List all milestones in a Linear project

NameTypeRequiredDescription

projectstringrequiredProject name, ID, or slug

linearmcp_list_project_labels#List available project labels in the Linear workspace4 params▾

List available project labels in the Linear workspace

NameTypeRequiredDescription

cursorstringoptionalNext page cursor

limitnumberoptionalMax results (default 50, max 250)

namestringoptionalFilter by name

orderBystringoptionalSort: createdAt | updatedAt

linearmcp_list_projects#List projects in the user's Linear workspace14 params▾

List projects in the user's Linear workspace

NameTypeRequiredDescription

createdAtstringoptionalCreated after: ISO-8601 date/duration (e.g., -P1D)

cursorstringoptionalNext page cursor

includeArchivedbooleanoptionalInclude archived projects

includeMembersbooleanoptionalInclude project members in results

includeMilestonesbooleanoptionalInclude project milestones in results

initiativestringoptionalFilter by initiative name or ID

labelstringoptionalFilter by label name or ID

limitnumberoptionalMax results (default 50, max 50)

memberstringoptionalFilter by member: user ID, name, email, or 'me'

orderBystringoptionalSort: createdAt | updatedAt

querystringoptionalSearch project name

statestringoptionalFilter by project state

teamstringoptionalFilter by team name or ID

updatedAtstringoptionalUpdated after: ISO-8601 date/duration (e.g., -P1D)

linearmcp_list_teams#List teams in the user's Linear workspace7 params▾

List teams in the user's Linear workspace

NameTypeRequiredDescription

createdAtstringoptionalCreated after ISO-8601

cursorstringoptionalNext page cursor

includeArchivedbooleanoptionalInclude archived teams

limitnumberoptionalMax results (default 50, max 250)

orderBystringoptionalSort: createdAt | updatedAt

querystringoptionalSearch query

updatedAtstringoptionalUpdated after ISO-8601

linearmcp_list_users#Retrieve users in the Linear workspace5 params▾

Retrieve users in the Linear workspace

NameTypeRequiredDescription

cursorstringoptionalPagination cursor from the previous response

limitnumberoptionalMaximum number of users to return

orderBystringoptionalField to order results by

querystringoptionalFilter by name or email

teamstringoptionalTeam name or ID to filter users

linearmcp_prepare_attachment_upload#Prepare a direct Linear file upload for an existing issue. Workflow: 1. Call this with issue, filename, contentType, and size. 2. Upload raw bytes with PUT to uploadRequest.url. 3. After PUT succeeds, call create_attachment_from_upload with assetUrl.6 params▾

Prepare a direct Linear file upload for an existing issue. Workflow: 1. Call this with issue, filename, contentType, and size. 2. Upload raw bytes with PUT to uploadRequest.url. 3. After PUT succeeds, call create_attachment_from_upload with assetUrl.

NameTypeRequiredDescription

contentTypestringrequiredMIME type, e.g. image/png or application/pdf

filenamestringrequiredFilename for the upload, e.g. screenshot.png

issuestringrequiredIssue ID or identifier (e.g., LIN-123)

sizeintegerrequiredExact file size in bytes. Must be smaller than 2 GB.

subtitlestringoptionalSuggested attachment subtitle for the finalize step

titlestringoptionalSuggested attachment title for the finalize step

linearmcp_save_comment#Create or update a comment on a Linear issue, project, initiative, document, or project milestone. If id is provided, updates the existing comment; otherwise creates a new one.8 params▾

Create or update a comment on a Linear issue, project, initiative, document, or project milestone. If id is provided, updates the existing comment; otherwise creates a new one.

NameTypeRequiredDescription

bodystringrequiredContent as Markdown. Use literal newlines and special characters.

documentIdstringoptionalDocument ID or slug (provide exactly one parent)

idstringoptionalComment ID. If provided, updates the existing comment

initiativeIdstringoptionalInitiative name or ID (provide exactly one parent)

issueIdstringoptionalIssue ID or identifier (e.g., LIN-123) (provide exactly one parent)

milestoneIdstringoptionalMilestone UUID (provide exactly one parent)

parentIdstringoptionalParent comment ID (for replies)

projectIdstringoptionalProject name, ID, or slug (provide exactly one parent)

linearmcp_save_document#Create or update a Linear document. If id is provided, updates the existing document; otherwise creates a new one. When creating, title is required and exactly one parent (project, issue, initiative, cycle, or team) must be specified.10 params▾

Create or update a Linear document. If id is provided, updates the existing document; otherwise creates a new one. When creating, title is required and exactly one parent (project, issue, initiative, cycle, or team) must be specified.

NameTypeRequiredDescription

colorstringoptionalHex color for the document

contentstringoptionalDocument content as Markdown

cyclestringoptionalCycle name, number, or ID to attach the document to

iconstringoptionalIcon name or emoji code for the document

idstringoptionalDocument ID or slug to update. Omit to create.

initiativestringoptionalInitiative name or ID to attach the document to

issuestringoptionalIssue ID or identifier to attach the document to (e.g. LIN-123)

projectstringoptionalProject name or ID to attach the document to

teamstringoptionalTeam name or ID to attach the document to

titlestringoptionalDocument title (required when creating)

linearmcp_save_issue#Create or update a Linear issue. If id is provided, updates the existing issue; otherwise creates a new one. When creating, title and team are required.23 params▾

Create or update a Linear issue. If id is provided, updates the existing issue; otherwise creates a new one. When creating, title and team are required.

NameTypeRequiredDescription

assigneestringoptionalUser ID, name, email, or 'me'. Pass null to remove assignee.

blockedByarrayoptionalIssue IDs that are blocking this issue

blocksarrayoptionalIssue IDs this issue blocks

cyclestringoptionalCycle name, number, or ID. Pass null to remove from cycle.

delegatestringoptionalAgent name or ID. Pass null to remove delegate.

descriptionstringoptionalIssue description as Markdown

dueDatestringoptionalDue date in ISO format

duplicateOfstringoptionalIssue ID this is a duplicate of. Pass null to remove.

estimatenumberoptionalIssue estimate value

idstringoptionalOnly for updating. Issue ID or identifier (e.g., LIN-123). Do NOT pass when creating.

labelsarrayoptionalLabel names or IDs to apply to the issue

linksarrayoptionalLink attachments to add to the issue [{url, title}]

milestonestringoptionalMilestone name or ID

parentIdstringoptionalParent issue ID or identifier. Pass null to remove parent.

prioritynumberoptional0=None, 1=Urgent, 2=High, 3=Medium, 4=Low

projectstringoptionalProject name, ID, or slug

relatedToarrayoptionalRelated issue IDs

removeBlockedByarrayoptionalBlocker issue IDs to remove

removeBlocksarrayoptionalIssue IDs to stop blocking

removeRelatedToarrayoptionalRelated issue IDs to remove

statestringoptionalState type, name, or ID

teamstringoptionalTeam name or ID (required when creating)

titlestringoptionalIssue title (required when creating)

linearmcp_save_milestone#Create or update a milestone in a Linear project. If id is provided, updates the existing milestone; otherwise creates a new one. When creating, name is required.5 params▾

Create or update a milestone in a Linear project. If id is provided, updates the existing milestone; otherwise creates a new one. When creating, name is required.

NameTypeRequiredDescription

projectstringrequiredProject name, ID, or slug

descriptionstringoptionalMilestone description

idstringoptionalMilestone name or ID. If provided, updates existing

namestringoptionalMilestone name (required when creating)

targetDatestringoptionalTarget completion date (ISO format, null to remove)

linearmcp_save_project#Create or update a Linear project. If id is provided, updates the existing project; otherwise creates a new one. When creating, name and at least one team are required.20 params▾

Create or update a Linear project. If id is provided, updates the existing project; otherwise creates a new one. When creating, name and at least one team are required.

NameTypeRequiredDescription

addInitiativesarrayoptionalInitiative names/IDs to add

addTeamsarrayoptionalTeam name or ID to add

colorstringoptionalHex color

descriptionstringoptionalContent as Markdown

iconstringoptionalIcon name or emoji code

idstringoptionalProject ID. If provided, updates existing

labelsarrayoptionalLabel names or IDs

leadstringoptionalUser ID, name, email, or 'me'. Null to remove

namestringoptionalProject name (required when creating)

priorityintegeroptional0=None, 1=Urgent, 2=High, 3=Medium, 4=Low

removeInitiativesarrayoptionalInitiative names/IDs to remove

removeTeamsarrayoptionalTeam name or ID to remove

setInitiativesarrayoptionalReplace all initiatives with these

setTeamsarrayoptionalReplace all teams with these

startDatestringoptionalStart date (ISO format)

startDateResolutionstringoptionalStart date resolution

statestringoptionalProject state

summarystringoptionalShort summary (max 255 chars)

targetDatestringoptionalTarget date (ISO format)

targetDateResolutionstringoptionalTarget date resolution

linearmcp_save_status_update#Create or update a project/initiative status update. Omit id to create, provide id to update.7 params▾

Create or update a project/initiative status update. Omit id to create, provide id to update.

NameTypeRequiredDescription

typestringrequiredType of status update — project or initiative

bodystringoptionalContent of the status update as Markdown

healthstringoptionalHealth status of the project or initiative

idstringoptionalStatus update ID — if provided, updates this existing update instead of creating a new one

initiativestringoptionalInitiative name or ID

isDiffHiddenbooleanoptionalDeprecated. Hide the diff with the previous update

projectstringoptionalProject name, ID, or slug

linearmcp_search_documentation#Search Linear's documentation to learn about features and usage2 params▾

Search Linear's documentation to learn about features and usage

NameTypeRequiredDescription

querystringrequiredSearch query to find relevant documentation

pagenumberoptionalPage number for paginated results