# Linear

```json
{
  "name": "Linear",
  "slug": "linear",
  "url": "https://composio.dev/toolkits/linear",
  "markdown_url": "https://composio.dev/toolkits/linear.md",
  "logo_url": "https://logos.composio.dev/api/linear",
  "categories": [
    "productivity & project management"
  ],
  "is_composio_managed": true,
  "updated_at": "2026-05-12T10:17:36.119Z"
}
```

![Linear logo](https://logos.composio.dev/api/linear)

## Description

Securely connect your AI agents and chatbots (Claude, ChatGPT, Cursor, etc) with Linear MCP or direct API to create, update, assign, and comment on issues through natural language.

## Summary

Linear is a modern issue tracking and project planning tool for fast-moving teams. It helps streamline workflows, organize projects, and boost productivity.

## Categories

- productivity & project management

## Toolkit Details

- Tools: 32
- Triggers: 3
- Managed auth: Managed by Composio

## Images

- Logo: https://logos.composio.dev/api/linear

## Authentication

- **Oauth2**
  - Type: `oauth2`
  - Description: Oauth2 authentication for Linear.
  - Setup:
    - Configure Oauth2 credentials for Linear.
    - Use the credentials when creating an auth config in Composio.
- **Api Key**
  - Type: `api_key`
  - Description: Api Key authentication for Linear.
  - Setup:
    - Configure Api Key credentials for Linear.
    - Use the credentials when creating an auth config in Composio.

## Suggested Prompts

- Create a new bug for team Mobile
- Add a comment to issue LIN-123
- List all cycles for the Design team
- Download the latest attachment from issue LIN-456

## Supported Tools

| Tool slug | Name | Description |
|---|---|---|
| `LINEAR_CREATE_ATTACHMENT` | Create attachment | Creates a new attachment and associates it with a specific, existing Linear issue. |
| `LINEAR_CREATE_COMMENT_REACTION` | Add reaction to comment | Tool to add a reaction to an existing Linear comment. Use when you want to programmatically react to a comment on an issue. |
| `LINEAR_CREATE_LINEAR_COMMENT` | Create a comment | Creates a new comment on a specified Linear issue. This action modifies shared workspace data and is not reversible — confirm the target issue and comment content before executing. |
| `LINEAR_CREATE_LINEAR_ISSUE` | Create linear issue | Creates a new issue in a specified Linear project and team, requiring team_id and title, and allowing optional properties like description, assignee, state, priority, cycle, and due date. All UUID parameters (state_id, assignee_id, cycle_id, label_ids, project_id) must belong to the same team as team_id. The created issue's id is returned in data.id — capture it for use as parent_id in sub-issues or follow-up operations. No template_id field exists; expand templates manually into title and description before calling. |
| `LINEAR_CREATE_LINEAR_ISSUE_RELATION` | Create issue relation | Create a relationship between two Linear issues using the issueRelationCreate mutation. Use this to establish connections like 'blocks', 'duplicate', or 'related' between issues. |
| `LINEAR_CREATE_LINEAR_LABEL` | Create a label | Creates a new label in Linear for a specified team, used to categorize and organize issues. Label names must be unique within each team. If a label with the same name already exists, the existing label will be returned. Both new and existing labels return the same object structure; check the label's `createdAt` or compare IDs to determine if creation occurred. |
| `LINEAR_CREATE_LINEAR_PROJECT` | Create Project | Creates a new Linear project with specified name and team associations. |
| `LINEAR_CREATE_PROJECT_MILESTONE` | Create Project Milestone | Tool to create a project milestone in Linear with a name and optional target date and sort order. Use when you need to add milestones to track progress within a project. |
| `LINEAR_CREATE_PROJECT_UPDATE` | Create Project Update | Tool to create a project status update post for a Linear project. Use when you need to post progress updates, status reports, or announcements for a project. |
| `LINEAR_DELETE_LINEAR_ISSUE` | Delete issue | Archives an existing Linear issue by its ID, which is Linear's standard way of deleting issues; the operation is idempotent. Archiving is permanent with no built-in undo — confirm the issue identifier and title with the user before executing, especially in bulk operations. |
| `LINEAR_GET_ATTACHMENT` | Download issue attachments | Downloads a specific attachment from a Linear issue; the `file_name` must include the correct file extension. |
| `LINEAR_GET_CURRENT_USER` | Get current user | Gets the currently authenticated user's ID, name, email, and other profile information — this is the account behind the API token, which may be a bot or service account rather than a human user. Use the returned `id` field (nested under `data.viewer`) for downstream Linear operations requiring user ID filtering. To search or compare other workspace members, use LINEAR_LIST_LINEAR_USERS instead. |
| `LINEAR_GET_CYCLES_BY_TEAM_ID` | Get cycles by team ID | Retrieves all cycles for a specified Linear team ID; cycles are time-boxed work periods (like sprints). Results are team-scoped to the given team_id. To identify the active cycle, check that the current date (in UTC) falls between a cycle's startAt and endAt fields; either field may be null. Results may be paginated — follow page_info cursors to retrieve all cycles. |
| `LINEAR_CREATE_LINEAR_ISSUE_DETAILS` | Get create issue default params | Fetches a Linear team's default issue estimate and state, useful for pre-filling new issue forms. |
| `LINEAR_GET_LINEAR_ISSUE` | Get Linear issue | Retrieves an existing Linear issue's comprehensive details, including id, identifier, title, description, timestamps, state, team, creator, attachments, comments (with user info and timestamps, use issue.comments.nodes for comment IDs), subscribers, and due date. Does not include parent, milestone, cycle, or relation graphs—use LINEAR_RUN_QUERY_OR_MUTATION for those. Optional fields (labels, project, state, assignee, cycle) may be null; guard against null when accessing nested properties. Returns null or 'Entity not found' for invalid IDs, cross-workspace IDs, or restricted teams. Rate limit: ~60 req/min; HTTP 429 on excess—apply exponential backoff and respect Retry-After headers. |
| `LINEAR_GET_LINEAR_PROJECT` | Get Linear project | Retrieves a single Linear project by its unique identifier. Use when verifying a newly created or updated project, or when fetching detailed project information by ID. |
| `LINEAR_LIST_ISSUE_DRAFTS` | List issue drafts | Tool to list issue drafts. Use when you need to fetch draft issues for review or further editing. Check `pageInfo.hasNextPage` in the response to determine if additional drafts exist beyond the current page. |
| `LINEAR_LIST_ISSUES_BY_TEAM_ID` | List issues by team ID | Tool to list all issues for a specific Linear team, scoped by team ID. Use when you need to retrieve issues belonging to a particular team without fetching workspace-wide issues. This is more efficient than workspace-wide listing followed by client-side filtering. |
| `LINEAR_LIST_LINEAR_CYCLES` | Get all cycles | Retrieves all cycles (time-boxed sprint iterations) org-wide from the Linear account; no filters applied. In large multi-team workspaces this produces heavy responses — filter client-side by team ID and date range using each cycle's startsAt/endsAt fields. Cycles are team-scoped; always group by team ID to avoid mixing sprints across teams. To identify the active sprint, verify the current UTC timestamp falls between startsAt and endsAt, and handle null startsAt/endsAt defensively. Timestamps are UTC. Results may be paginated; follow pageInfo.endCursor and hasNextPage until hasNextPage is false to avoid truncated lists. |
| `LINEAR_LIST_LINEAR_ISSUES` | List Linear issues | Lists non-archived Linear issues; if project_id is not specified, issues from all accessible projects are returned. Can filter by assignee_id. Only project_id and assignee_id server-side filters are supported; label, state, team, cycle, or date filters must be done client-side or via LINEAR_RUN_QUERY_OR_MUTATION. Response is a flat issues array plus page_info object (not GraphQL nodes/pageInfo). Fields like cycle membership, dueDate, completedAt, comments, and attachments are absent; use LINEAR_GET_LINEAR_ISSUE for enrichment. state and labels are nested objects (labels as labels.nodes array). Response order is not guaranteed; sort client-side after collecting all pages. No team_id filter; scope by project_id or use LINEAR_RUN_QUERY_OR_MUTATION. |
| `LINEAR_LIST_LINEAR_LABELS` | Get labels | Retrieves labels from Linear. If team_id is provided, returns labels for that specific team; if omitted, returns all labels across the workspace. Label names are not unique across teams — always use returned IDs, not names, and track each label ID with its team ID. In large workspaces, results may paginate; follow pageInfo.hasNextPage and pageInfo.endCursor to retrieve all labels. |
| `LINEAR_LIST_LINEAR_PROJECTS` | List linear projects | Retrieves all projects from the Linear account. Returns a flat array (not a GraphQL connection) with fields id and name; use LINEAR_RUN_QUERY_OR_MUTATION for progress, state, issues, or team linkage. No server-side filtering: all workspace projects are returned regardless of team or name — filter client-side. Multiple projects can share identical names; always confirm project_id before downstream use. Results are permission-scoped to the connected user. Pagination: loop while page_info.hasNextPage is true, passing page_info.endCursor as after, or results will be silently truncated. HTTP 429 may occur in large workspaces; apply exponential backoff between calls. |
| `LINEAR_LIST_LINEAR_STATES` | List Linear states | Retrieves all workflow states for a specified team in Linear, representing the stages an issue progresses through in that team's workflow. Returned state IDs are team-scoped — never reuse a stateId across different teams, as this causes validation errors or 'Entity not found' failures in tools like LINEAR_UPDATE_ISSUE. State names (e.g., 'Done', 'In Progress') are non-unique across teams; always resolve names to IDs via this tool for the specific team_id before using them in filters or mutations. Uses cursor-based pagination via pageInfo.hasNextPage and endCursor; iterate until hasNextPage is false to avoid missing states in large workspaces. Always fetch fresh state IDs rather than hardcoding or reusing stale values. |
| `LINEAR_LIST_LINEAR_TEAMS` | Get teams | Retrieves all teams with their members and projects. Use stable team IDs or keys (not display names) for subsequent operations — names are non-unique. Results reflect only teams visible to the authenticated token scope; missing teams or members indicate permission limits. Large workspaces paginate via pageInfo.hasNextPage/endCursor — incomplete pagination silently drops teams or members. Members may belong to multiple teams; deduplicate user IDs when aggregating. Use LINEAR_GET_ALL_LINEAR_TEAMS instead when only identifiers are needed. |
| `LINEAR_LIST_LINEAR_USERS` | List Linear users | Lists all workspace users (not team-scoped) with their IDs, names, emails, and active status. Display names are non-unique — use email to disambiguate before extracting an ID. Only assign users with `active: true`. Returned IDs are UUID strings; pass them as-is to fields like `assignee_id` — never substitute names, emails, or tokens. When joining with other tools, always join on IDs. |
| `LINEAR_REMOVE_ISSUE_LABEL` | Remove label from Linear issue | Removes a specified label from an existing Linear issue using their IDs; successful even if the label isn't on the issue. Operation is irreversible — obtain explicit user approval before executing. Use this tool instead of LINEAR_UPDATE_ISSUE to avoid replacing the entire label set. |
| `LINEAR_REMOVE_REACTION` | Remove reaction from comment | Tool to remove a reaction on a comment. Use when you have a reaction ID and need to delete it. |
| `LINEAR_RUN_QUERY_OR_MUTATION` | Run Query or Mutation | Execute any GraphQL query or mutation against Linear's API. USE WHEN: No dedicated action exists, need complex filtering, custom fields, or schema discovery. *** INTROSPECTION FIRST - NEVER GUESS FIELD NAMES *** Run introspection before unknown operations: - query { __type(name: "Issue") { fields { name } } } - query { __type(name: "Mutation") { fields { name } } } Linear uses nested objects (project { id }), NOT scalar IDs (projectId). KEY: All IDs are UUIDs. Filter: { field: { eq: value } }. Pagination: nodes[] + pageInfo. |
| `LINEAR_SEARCH_ISSUES` | Search Linear issues | Search Linear issues using full-text search across identifier, title, and description. Use when you need to find issues by keywords or specific identifiers. Note: This endpoint only supports full-text search; for structured filtering by team, project, assignee, state, or labels, use LIST_ISSUES_BY_TEAM_ID instead. |
| `LINEAR_UPDATE_ISSUE` | Update issue | Updates an existing Linear issue using its `issue_id`; requires at least one other attribute for modification, and all provided entity IDs (for state, assignee, labels, etc.) must be valid UUIDs — only `issueId` accepts key format (e.g., 'ENG-123'). All updated fields are fully overwritten, not merged; omit any field you do not intend to change. |
| `LINEAR_UPDATE_LINEAR_COMMENT` | Update a comment | Tool to update an existing Linear comment's body text. Use when you need to edit or modify the content of a previously created comment. |
| `LINEAR_UPDATE_LINEAR_PROJECT` | Update Project | Tool to update an existing Linear project. Use when you need to modify project properties like name, description, state, dates, or lead. All fields except project_id are optional - only provide the fields you want to update. |

## Supported Triggers

| Trigger slug | Name | Description |
|---|---|---|
| `LINEAR_COMMENT_EVENT_TRIGGER` | Comment Received Trigger | Triggered when a comment is received. |
| `LINEAR_ISSUE_CREATED_TRIGGER` | Issue Created Trigger | Triggered when a new issue is created. |
| `LINEAR_ISSUE_UPDATED_TRIGGER` | Issue Updated Trigger | Triggered when an issue is updated. For example labels are changed, issue status is changed, etc. |

## Installation and MCP Setup

### Path 1: SDK Installation

#### Path 1, Step 1: Install Composio

Install the Composio SDK
```python
pip install composio_openai
```

```typescript
npm install @composio/openai
```

#### Path 1, Step 2: Initialize Composio and Create Tool Router Session

Import and initialize Composio client, then create a Tool Router session
```python
from openai import OpenAI
from composio import Composio
from composio_openai import OpenAIResponsesProvider

composio = Composio(provider=OpenAIResponsesProvider())
openai = OpenAI()
session = composio.create(user_id='your-user-id')
```

```typescript
import OpenAI from 'openai';
import { Composio } from '@composio/core';
import { OpenAIResponsesProvider } from '@composio/openai';

const composio = new Composio({
  provider: new OpenAIResponsesProvider(),
});
const openai = new OpenAI({});
const session = await composio.create('your-user-id');
```

#### Path 1, Step 3: Execute Linear Tools via Tool Router with Your Agent

Get tools from Tool Router session and execute Linear actions with your Agent
```python
tools = session.tools
response = openai.responses.create(
  model='gpt-4.1',
  tools=tools,
  input=[{
    'role': 'user',
    'content': 'List all open Linear issues assigned to me this week'
  }]
)
result = composio.provider.handle_tool_calls(
  response=response,
  user_id='your-user-id'
)
print(result)
```

```typescript
const tools = session.tools;
const response = await openai.responses.create({
  model: 'gpt-4.1',
  tools: tools,
  input: [{
    role: 'user',
    content: 'List all open Linear issues assigned to me this week'
  }],
});
const result = await composio.provider.handleToolCalls(
  'your-user-id',
  response.output
);
console.log(result);
```

### Path 2: MCP Server Setup

#### Path 2, Step 1: Install Composio

Install the Composio SDK and Claude Agent SDK
```python
pip install composio claude-agent-sdk
```

```typescript
npm install @composio/core ai @ai-sdk/openai @ai-sdk/mcp
```

#### Path 2, Step 2: Create Tool Router Session

Initialize the Composio client and create a Tool Router session
```python
from composio import Composio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

composio = Composio(api_key='your-composio-api-key')
session = composio.create(user_id='your-user-id')
url = session.mcp.url
```

```typescript
import { Composio } from '@composio/core';

const composio = new Composio({ apiKey: 'your-api-key' });

console.log("Creating Tool Router session...");
const { mcp } = await composio.create('your-user-id');
console.log(`Tool Router session created: ${mcp.url}`);
```

#### Path 2, Step 3: Connect to AI Agent

Use the MCP server with your AI agent
```python
import asyncio

options = ClaudeAgentOptions(
    permission_mode='bypassPermissions',
    mcp_servers={
        'tool_router': {
            'type': 'http',
            'url': url,
            'headers': {
                'x-api-key': 'your-composio-api-key'
            }
        }
    },
    system_prompt='You are a helpful assistant with access to Linear tools.',
    max_turns=10
)

async def main():
    async with ClaudeSDKClient(options=options) as client:
        await client.query('Create a new Linear issue titled "Bug: Login page fails on submit" in the Web team project')
        async for message in client.receive_response():
            if hasattr(message, 'content'):
                for block in message.content:
                    if hasattr(block, 'text'):
                        print(block.text)

asyncio.run(main())
```

```typescript
import { openai } from '@ai-sdk/openai';
import { experimental_createMCPClient as createMCPClient } from '@ai-sdk/mcp';
import { generateText, stepCountIs } from 'ai';

const client = await createMCPClient({
  transport: {
    type: 'http',
    url: mcp.url,
    headers: { 'x-api-key': 'your-composio-api-key' }
  }
});

const tools = await client.tools();

const { text } = await generateText({
  model: openai('gpt-4o'),
  tools,
  messages: [{ role: 'user', content: 'Create a new Linear issue titled "Bug: Login page fails on submit" in the Web team project' }],
  stopWhen: stepCountIs(5)
});

console.log(`Agent: ${text}`);
```

## Why Use Composio?

### 1. AI Native Linear Integration

- Supports both Linear MCP and direct API based integrations
- Structured, LLM-friendly schemas for reliable tool execution
- Rich coverage for reading, writing, and querying your Linear data

### 2. Managed Auth

- Built-in OAuth handling with automatic token refresh and rotation
- Central place to manage, scope, and revoke Linear access
- Per user and per environment credentials instead of hard-coded keys

### 3. Agent Optimized Design

- Tools are tuned using real error and success rates to improve reliability over time
- Comprehensive execution logs so you always know what ran, when, and on whose behalf

### 4. Enterprise Grade Security

- Fine-grained RBAC so you control which agents and users can access Linear
- Scoped, least privilege access to Linear resources
- Full audit trail of agent actions to support review and compliance

## Use Linear with any AI Agent Framework

Choose a framework you want to connect Linear with:

- [ChatGPT](https://composio.dev/toolkits/linear/framework/chatgpt)
- [OpenAI Agents SDK](https://composio.dev/toolkits/linear/framework/open-ai-agents-sdk)
- [Claude Agent SDK](https://composio.dev/toolkits/linear/framework/claude-agents-sdk)
- [Claude Code](https://composio.dev/toolkits/linear/framework/claude-code)
- [Claude Cowork](https://composio.dev/toolkits/linear/framework/claude-cowork)
- [Codex](https://composio.dev/toolkits/linear/framework/codex)
- [Cursor](https://composio.dev/toolkits/linear/framework/cursor)
- [VS Code](https://composio.dev/toolkits/linear/framework/vscode)
- [OpenCode](https://composio.dev/toolkits/linear/framework/opencode)
- [OpenClaw](https://composio.dev/toolkits/linear/framework/openclaw)
- [Hermes](https://composio.dev/toolkits/linear/framework/hermes-agent)
- [CLI](https://composio.dev/toolkits/linear/framework/cli)
- [Google ADK](https://composio.dev/toolkits/linear/framework/google-adk)
- [LangChain](https://composio.dev/toolkits/linear/framework/langchain)
- [Vercel AI SDK](https://composio.dev/toolkits/linear/framework/ai-sdk)
- [Mastra AI](https://composio.dev/toolkits/linear/framework/mastra-ai)
- [LlamaIndex](https://composio.dev/toolkits/linear/framework/llama-index)
- [CrewAI](https://composio.dev/toolkits/linear/framework/crew-ai)
- [Pydantic AI](https://composio.dev/toolkits/linear/framework/pydantic-ai)
- [AutoGen](https://composio.dev/toolkits/linear/framework/autogen)

## Related Toolkits

- [Google Sheets](https://composio.dev/toolkits/googlesheets) - Google Sheets is a cloud-based spreadsheet tool for real-time collaboration and data analysis. It lets teams work together from anywhere, updating information instantly.
- [Notion](https://composio.dev/toolkits/notion) - Notion is a collaborative workspace for notes, docs, wikis, and tasks. It streamlines team knowledge, project tracking, and workflow customization in one place.
- [Airtable](https://composio.dev/toolkits/airtable) - Airtable combines the flexibility of spreadsheets with the power of a database for easy project and data management. Teams use Airtable to organize, track, and collaborate with custom views and automations.
- [Asana](https://composio.dev/toolkits/asana) - Asana is a collaborative work management platform for teams to organize and track projects. It streamlines teamwork, boosts productivity, and keeps everyone aligned on goals.
- [Google Tasks](https://composio.dev/toolkits/googletasks) - Google Tasks is a to-do list and task management tool integrated into Gmail and Google Calendar. It helps you organize, track, and complete tasks across your Google ecosystem.
- [Jira](https://composio.dev/toolkits/jira) - Jira is Atlassian’s platform for bug tracking, issue tracking, and agile project management. It helps teams organize work, prioritize tasks, and deliver projects efficiently.
- [Clickup](https://composio.dev/toolkits/clickup) - ClickUp is an all-in-one productivity platform for managing tasks, docs, goals, and team collaboration. It streamlines project workflows so teams can work smarter and stay organized in one place.
- [Monday](https://composio.dev/toolkits/monday) - Monday.com is a customizable work management platform for project planning and collaboration. It helps teams organize tasks, automate workflows, and track progress in real time.
- [Addressfinder](https://composio.dev/toolkits/addressfinder) - Addressfinder is a data quality platform for verifying addresses, emails, and phone numbers. It helps you ensure accurate customer and contact data every time.
- [Agiled](https://composio.dev/toolkits/agiled) - Agiled is an all-in-one business management platform for CRM, projects, and finance. It helps you streamline workflows, consolidate client data, and manage business processes in one place.
- [Ascora](https://composio.dev/toolkits/ascora) - Ascora is a cloud-based field service management platform for service businesses. It streamlines scheduling, invoicing, and customer operations in one place.
- [Basecamp](https://composio.dev/toolkits/basecamp) - Basecamp is a project management and team collaboration tool by 37signals. It helps teams organize tasks, share files, and communicate efficiently in one place.
- [Beeminder](https://composio.dev/toolkits/beeminder) - Beeminder is an online goal-tracking platform that uses monetary pledges to keep you motivated. Stay accountable and hit your targets with real financial incentives.
- [Boxhero](https://composio.dev/toolkits/boxhero) - Boxhero is a cloud-based inventory management platform for SMBs, offering real-time updates, barcode scanning, and team collaboration. It helps businesses streamline stock tracking and analytics for smarter inventory decisions.
- [Breathe HR](https://composio.dev/toolkits/breathehr) - Breathe HR is cloud-based HR software for SMEs to manage employee data, absences, and performance. It simplifies HR admin, making it easy to keep employee records accurate and up to date.
- [Breeze](https://composio.dev/toolkits/breeze) - Breeze is a project management platform designed to help teams plan, track, and collaborate on projects. It streamlines workflows and keeps everyone on the same page.
- [Bugherd](https://composio.dev/toolkits/bugherd) - Bugherd is a visual feedback and bug tracking tool for websites. It helps teams and clients report website issues directly on live sites for faster fixes.
- [Canny](https://composio.dev/toolkits/canny) - Canny is a platform for managing customer feedback and feature requests. It helps teams prioritize product decisions based on real user insights.
- [Chmeetings](https://composio.dev/toolkits/chmeetings) - Chmeetings is a church management platform for events, members, donations, and volunteers. It streamlines church operations and improves community engagement.
- [ClickSend](https://composio.dev/toolkits/clicksend) - ClickSend is a cloud-based SMS and email marketing platform for businesses. It streamlines communication by enabling quick message delivery and contact management.

## Frequently Asked Questions

### Do I need my own developer credentials to use Linear with Composio?

No, you can get started immediately using Composio's built-in Linear app. For production, we recommend configuring your own OAuth credentials.

### Can I use multiple toolkits together?

Yes! Composio's Tool Router enables agents to use multiple toolkits. [Learn more](https://docs.composio.dev/tool-router/overview).

### Is Composio secure?

Composio is SOC 2 and ISO 27001 compliant with all data encrypted in transit and at rest. [Learn more](https://trust.composio.dev).

### What if the API changes?

Composio maintains and updates all toolkit integrations automatically, so your agents always work with the latest API versions.

---
[See all toolkits](https://composio.dev/toolkits) · [Composio docs](https://docs.composio.dev/llms.txt)