Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/dvlpjrs/guMCP/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Linear server enables AI agents to search, create, and update issues in Linear. It provides comprehensive issue tracking and project management capabilities.

​
Prerequisites

  • Python 3.11+
  • A Linear App with OAuth configured
  • OAuth scopes: read, write

​
Authentication

​
Create Linear OAuth App

  1. Follow the Linear OAuth Authentication guide
  2. Create an OAuth application
  3. Note your Client ID, Client Secret, and Redirect URI

​
Setup OAuth Configuration

Create local_auth/oauth_configs/linear/oauth.json: 
{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "your_redirect_uri"
}

​
Authenticate

python src/servers/linear/main.py auth

​
Available Tools

Description: Search for issues in LinearParameters:
  • query (string, required): Search query for issues
Example:
{
  "query": "authentication bug"
}
Returns: List of matching issues with details (title, state, priority, assignee)
Description: Create a new issue in LinearParameters:
  • team_id (string, required): ID of the team
  • title (string, required): Issue title
  • description (string, optional): Issue description
  • priority (integer, optional): Priority (1-4, where 1 is highest)
  • assignee_id (string, optional): ID of user to assign
  • label_ids (array, optional): Array of label IDs to apply
Example:
{
  "team_id": "team_abc123",
  "title": "Fix login authentication error",
  "description": "Users are unable to login with Google OAuth",
  "priority": 1,
  "assignee_id": "user_xyz789"
}
Returns: Created issue details with ID and URL
Description: Update an existing issue in LinearParameters:
  • issue_id (string, required): ID of the issue to update
  • title (string, optional): New title
  • description (string, optional): New description
  • state_id (string, optional): New state ID
  • priority (integer, optional): New priority (1-4)
  • assignee_id (string, optional): New assignee ID
  • label_ids (array, optional): New label IDs
Example:
{
  "issue_id": "issue_123abc",
  "state_id": "state_completed",
  "priority": 3
}
Returns: Updated issue details

​
Resources

The Linear server provides access to teams and issues:

​
List Resources

Lists:
  • All your teams
  • Recent issues from each team (up to 10 per team)
URI Formats:
  • linear:///team/{team_id} - Team details
  • linear:///issue/{issue_id} - Issue details

​
Read Resource

Reads complete details including:
  • Issue metadata (title, identifier, state)
  • Team information
  • Assignee details
  • Labels and priority
  • Comments with timestamps

​
Usage Examples

​
Searching Issues

# Search by keyword
issues = await call_tool("search_issues", {
    "query": "authentication"
})

# Search for bugs
issues = await call_tool("search_issues", {
    "query": "bug"
})

​
Creating Issues

# Create a simple issue
await call_tool("create_issue", {
    "team_id": "team_abc123",
    "title": "Add dark mode support",
    "description": "Users have requested a dark mode option for the dashboard"
})

# Create a high-priority bug with assignment
await call_tool("create_issue", {
    "team_id": "team_abc123",
    "title": "Critical: Database connection failing",
    "description": "Production database connections are timing out",
    "priority": 1,
    "assignee_id": "user_xyz789",
    "label_ids": ["label_bug", "label_critical"]
})

​
Updating Issues

# Mark issue as completed
await call_tool("update_issue", {
    "issue_id": "issue_123abc",
    "state_id": "state_completed"
})

# Reassign and change priority
await call_tool("update_issue", {
    "issue_id": "issue_123abc",
    "assignee_id": "user_xyz789",
    "priority": 2
})

# Update title and description
await call_tool("update_issue", {
    "issue_id": "issue_123abc",
    "title": "[Updated] Fix login authentication",
    "description": "Updated description with more details..."
})

​
Priority Levels

Linear uses numeric priorities:
PriorityValueUsage
Urgent1Critical issues requiring immediate attention
High2Important issues to address soon
Medium3Standard priority issues
Low4Nice-to-have improvements
NonenullNo priority set

​
Finding IDs

​
Team ID

Use list_resources() to discover team IDs: 
resources = await list_resources()
for resource in resources:
    if "Team:" in resource.name:
        print(f"Team: {resource.name}, URI: {resource.uri}")
        # Extract team_id from URI: linear:///team/{team_id}

​
Issue ID

Returned when creating an issue or from search results.

​
State ID

Read a team resource to see available states: 
team_data = await read_resource("linear:///team/{team_id}")
# Contains states.nodes with state IDs and names

​
Issue Identifiers

Linear uses human-readable identifiers like ENG-123:
  • ENG - Team key
  • 123 - Issue number
These are different from issue IDs used by the API.

​
Running the Server

​
Local Development

python src/servers/local.py --server linear --user-id local

​
Best Practices

  1. Use descriptive titles: Clear, concise issue titles
  2. Set priorities: Help teams prioritize work
  3. Assign ownership: Use assignee_id for accountability
  4. Add labels: Categorize issues with labels
  5. Search first: Check for duplicates before creating issues

​
API Reference

ToolPurposeCommon Use Cases
search_issuesFind issuesSearch bugs, find tasks
create_issueCreate issuesReport bugs, create tasks
update_issueModify issuesUpdate status, reassign

​
GraphQL API

Linear uses GraphQL. The server handles query construction, but you can reference the Linear API docs for advanced use cases.

Build docs developers (and LLMs) love

Get started for freeTalk to us