Linear Server

Overview

The Linear server provides comprehensive project management and issue tracking capabilities. Built by Linear, this server enables AI assistants to manage issues, coordinate projects, track sprints, and streamline development workflows.

Getting Started

1. 1
   Connect to Linear

   Add the Linear server to your Civic environment through the server directory.

2. 2
   Authenticate with Linear

   Connect your Linear workspace using OAuth to access your teams and projects.

3. 3
   Test Connection

   Start with get user to verify authentication and list teams to see your workspace structure.

What You Can Do

Issue Management

Create, update, search, and track issues across teams and projects

Project Coordination

Manage projects, assign leads, set timelines, and track progress

Team Organization

Coordinate teams, workflows, and sprint cycles for efficient delivery

Workflow Automation

Automate issue creation, updates, and status transitions based on development events

Use Cases

Issue Tracking & Management

• Bug Reporting: Create detailed bug reports with descriptions, priorities, and assignments
• Feature Requests: Track feature development from concept to completion
• Task Management: Organize development tasks with estimates and deadlines
• Status Tracking: Monitor issue progress through customizable workflow states

Project Planning & Execution

• Project Setup: Create projects with timelines, leads, and team assignments
• Sprint Planning: Organize work into cycles with clear start and end dates
• Progress Monitoring: Track project completion and identify blockers
• Resource Allocation: Balance workload across team members and projects

Team Collaboration

• Cross-team Coordination: Manage dependencies between different teams
• Communication: Add comments and updates to issues for clear communication
• Assignment Management: Distribute work based on expertise and availability
• Workflow Standardization: Ensure consistent processes across teams

Development Integration

• Code-to-Issue Linking: Connect code changes to specific Linear issues
• Automated Updates: Update issue status based on Git commits and deployments
• Release Planning: Organize issues into releases and track completion
• Quality Assurance: Track testing, reviews, and deployment status

---

Available Tools (26)

User & Team Management (3 tools)

Essential tools for understanding workspace structure and team organization.

Workspace Discovery

get_user

Get information about the authenticated Linear user and workspace access

list_teams

List all teams in the workspace with optional archived team inclusion

• Parameters: includeArchived (boolean, default: false)

list_users

List all users in the workspace with activity status

• Parameters: includeInactive (boolean, default: false)

info

Team IDs: Required for most operations - get them via list_teams first.

Issue Operations (5 tools)

Core functionality for creating, updating, and managing Linear issues.

Issue Lifecycle Management

search_issues

Advanced issue search with multiple filter options

• Filters: query, teamId, projectId, assigneeId, state, limit (1-100)
• States: backlog, todo, in_progress, done, canceled

get_issue

Get detailed information about specific issues

• Input: Issue ID or issue number (e.g., 'ENG-123')

create_issue

Create new issues with full metadata support

• Required: title, teamId
• Optional: description, projectId, assigneeId, priority (0-4), labelIds, estimate

update_issue

Update existing issues with flexible field modifications

• Updatable: title, description, stateId, assigneeId, priority, labelIds, estimate

add_comment

Add markdown-formatted comments to issues for collaboration

• Parameters: issueId (required), body (markdown format)

note

Priority Levels: 0=No priority, 1=Urgent, 2=High, 3=Normal, 4=Low

Project Management (3 tools)

Tools for organizing work into projects and tracking progress.

list_projects

List projects with team and archive filtering

• Parameters: teamId (optional), includeArchived (boolean, default: false)

create_project

Create new projects with timeline and team assignments

• Required: name, teamIds (array)
• Optional: description, leadId, targetDate, startDate (YYYY-MM-DD)

list_cycles

List sprint cycles for agile development

• Parameters: teamId (required), includeCompleted (boolean, default: false)

tip

Date Format: Use ISO date format (YYYY-MM-DD) for startDate and targetDate parameters.

Workflow & Configuration (3 tools)

Tools for managing workflow states, labels, and team configuration.

list_workflows

Get workflow states and transitions for specific teams

• Parameters: teamId (required)
• Use Cases: Understand available states for issue updates

list_labels

List available labels for categorizing and organizing issues

• Parameters: teamId (optional filter)
• Use Cases: Get label IDs for issue creation and updates

warning

Always use list_workflows to get valid stateIds before updating issue states.

---

Configuration Requirements

Authentication Setup

The Linear server uses OAuth2 authentication with Linear's API:

OAuth Scopes

• Read Access: View issues, projects, teams, and user data
• Write Access: Create and update issues, projects, and comments
• Workspace Access: Access to all teams and projects in your workspace

Required Permissions

• Team Member: Must be a member of teams you want to manage
• Project Access: View and edit permissions for relevant projects
• Issue Management: Create, update, and comment permissions
• User Directory: Access to workspace user list for assignments

Best Practices

Issue Management Workflow

1. Team Discovery: Use list_teams to understand workspace structure
2. Issue Creation: Use create_issue with appropriate team, priority, and labels
3. Progress Tracking: Use search_issues with state filters to monitor progress
4. Status Updates: Use update_issue to move issues through workflow states
5. Communication: Use add_comment for updates and collaboration

Project Planning Best Practices

1. Project Setup: Use create_project with clear timelines and team assignments
2. Sprint Organization: Use list_cycles to plan work in iterations
3. Workload Distribution: Balance assignments using list_users and search filters
4. Progress Monitoring: Track project completion with filtered issue searches

Workflow Optimization

1. State Management: Use list_workflows to understand available transitions
2. Label Strategy: Use list_labels to maintain consistent categorization
3. Automation: Create issues automatically based on errors, deployments, or events
4. Integration: Link issues to code commits, pull requests, and deployments

Team Coordination

1. Assignment Strategy: Assign issues based on expertise and current workload
2. Priority Management: Use priority levels consistently across teams
3. Communication: Keep issue comments updated with progress and blockers
4. Cross-team Dependencies: Use projects to coordinate work between teams

warning

Always verify team IDs, user IDs, and state IDs using the list tools before creating or updating issues.

tip

Pro Tip: Use descriptive issue titles and markdown-formatted descriptions for better searchability and team communication.

---

Guardrails

In addition to the 14 universal guardrails, this server has 12 server-specific guardrails across 8 operations.

Guardrail	Operation	Timing	Description
Block Issue Creation in Non-Vetted Teams	create_issue	Request	Prevent creating issues in teams that are not vetted
Block Project Creation in Non-Vetted Teams	create_project	Request	Prevent creating projects in teams that are not vetted
Restrict to Vetted Project Names	get_project	Request	Only allow queries for whitelisted Linear project names
Restrict to Vetted Team Names	get_team	Request	Only allow queries for whitelisted Linear team names
Block Email Addresses in Searches	get_user	Request	Prevent searching for users by email address
Filter Issues to Vetted Projects	list_issues	Response	Redact issues that don't belong to vetted projects
Restrict to Vetted Team IDs	list_issue_statuses	Request	Only allow queries for whitelisted Linear team IDs
Filter Projects to Vetted List	list_projects	Response	Redact projects that are not on the vetted list
Redact User Admin Status	list_users	Response	Redact admin status from user data to prevent privilege discovery
Redact User Last Seen Status	list_users	Response	Redact last seen timestamps to protect user privacy
Restrict to Vetted Project IDs	update_project	Request	Only allow operations on whitelisted Linear project IDs
Redact Workspace URLs	(all operations)	Response	Redact Linear workspace URLs to prevent workspace enumeration

tip

Configure guardrails via the Civic UI or ask the Configurator Agent: "Add guardrails to my Linear server."