MCP Linear.app Server

A Model Context Protocol (MCP) server that enables OpenCode and other MCP clients to interact with Linear.app's API for issue tracking, project management, and workflow automation.

Features

• Issue Management: Create, update, list, search, and get detailed issue information

• Project & Team Operations: List projects and teams, access workflow states

• Cycle Management: Create and manage sprints/cycles

• Label Management: Create and organize labels

• User Operations: List users and assign issues

• Advanced Filtering: Filter issues by status, assignee, project, labels, and more

• Type-Safe: Built with TypeScript and Zod validation for robust error handling

• Production-Ready: Comprehensive error handling, logging, and rate limit awareness

Installation

Prerequisites

• Bun 1.0.0 or higher (or Node.js 18.0.0+)

• A Linear.app account and API key

Setup

1. Clone this repository:

git clone <repository-url>
cd mcp-linearapp

2. Install dependencies:

bun install

3. Create a .env file with your Linear API key:

cp .env.example .env

4. Edit .env and add your Linear API key:

LINEAR_API_KEY=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

How to get your Linear API key:

1. Go to https://linear.app/settings/api

2. Click "Create new API key"

3. Give it a name and copy the key

4. Paste it into your .env file

5. Build the project:

bun run build

Usage

With OpenCode

Add this server to your OpenCode configuration:

macOS: ~/Library/Application Support/OpenCode/opencode_config.json
Windows: %APPDATA%/OpenCode/opencode_config.json
Linux: ~/.config/OpenCode/opencode_config.json

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-linearapp/dist/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

After adding the configuration, restart OpenCode.

With Other MCP Clients

The server uses stdio transport and can be integrated with any MCP-compatible client:

bun run dist/index.js
# or with Node.js:
node dist/index.js

Available Tools

Issue Management

linear_list_issues

List Linear issues with optional filters.

Parameters:

• teamId (optional): Filter by team ID

• projectId (optional): Filter by project ID

• assigneeId (optional): Filter by assignee user ID

• status (optional): Filter by status (backlog, unstarted, started, completed, canceled, triage, in_progress, done)

• priority (optional): Filter by priority (0=None, 1=Urgent, 2=High, 3=Medium, 4=Low)

• label (optional): Filter by label name

• limit (optional): Maximum number of issues (1-100, default: 25)

• includeArchived (optional): Include archived issues (default: false)

Example:

List all high priority issues assigned to me

linear_create_issue

Create a new Linear issue.

Parameters:

• title (required): Issue title

• teamId (required): Team ID where the issue will be created

• description (optional): Issue description in markdown

• projectId (optional): Project ID to assign the issue to

• assigneeId (optional): User ID to assign the issue to

• priority (optional): Priority (0-4)

• labelIds (optional): Array of label IDs

• stateId (optional): Workflow state ID

• estimate (optional): Estimate in points

• dueDate (optional): Due date (YYYY-MM-DD)

• parentId (optional): Parent issue ID for sub-issues

Example:

Create an issue titled "Fix login bug" in the Engineering team with high priority

linear_update_issue

Update an existing Linear issue.

Parameters:

• issueId (required): Issue ID or identifier (e.g., "ENG-123")

• title, description, assigneeId, priority, stateId, labelIds, estimate, dueDate, projectId (all optional)

Example:

Update issue ENG-123 to change priority to urgent and assign to John

linear_get_issue

Get detailed information about a specific issue.

Parameters:

• issueId (required): Issue ID or identifier (e.g., "ENG-123")

Example:

Get details for issue ENG-123

linear_search_issues

Search issues by text query.

Parameters:

• query (required): Search query text

• teamId (optional): Limit search to specific team

• limit (optional): Maximum results (1-100, default: 25)

• includeArchived (optional): Include archived issues

Example:

Search for issues about authentication

linear_assign_issue

Assign an issue to a user.

Parameters:

• issueId (required): Issue ID or identifier

• assigneeId (required): User ID to assign to

Example:

Assign issue ENG-123 to user abc-123

linear_add_comment

Add a comment to an issue.

Parameters:

• issueId (required): Issue ID or identifier

• body (required): Comment body in markdown

Example:

Add a comment to ENG-123 saying "This is fixed in the latest build"

Team & Workflow

linear_list_teams

List all teams in your workspace.

Parameters:

• includeArchived (optional): Include archived teams (default: false)

Example:

List all teams

linear_list_workflow_states

List workflow states for a team.

Parameters:

• teamId (required): Team ID

Example:

List workflow states for team abc-123

Projects

linear_list_projects

List all projects.

Parameters:

• teamId (optional): Filter by team ID

• includeArchived (optional): Include archived projects (default: false)

Example:

List all projects for the Engineering team

Cycles (Sprints)

linear_create_cycle

Create a new cycle/sprint.

Parameters:

• teamId (required): Team ID

• name (required): Cycle name

• description (optional): Cycle description

• startsAt (required): Start date (YYYY-MM-DD)

• endsAt (required): End date (YYYY-MM-DD)

Example:

Create a 2-week sprint starting today for the Engineering team

linear_list_cycles

List cycles for a team.

Parameters:

• teamId (required): Team ID

• includeArchived (optional): Include archived cycles

Example:

List all active cycles for team abc-123

Labels

linear_create_label

Create a new label.

Parameters:

• name (required): Label name

• teamId (required): Team ID

• color (optional): Color in hex format (e.g., "#FF0000")

• description (optional): Label description

Example:

Create a label called "bug" with red color for the Engineering team

linear_list_labels

List all labels.

Parameters:

• teamId (optional): Filter by team ID

Example:

List all labels

Users

linear_list_users

List all users in your workspace.

Parameters:

• includeDisabled (optional): Include disabled users (default: false)

Example:

List all active users

Workflow Examples

Creating an Issue with Full Context

1. First, list teams to get the team ID:

List all teams

2. Optionally, list users to assign the issue:

List all users

3. Create the issue:

Create an issue titled "Implement OAuth authentication" in team abc-123, assign to user xyz-456, with high priority and description "Need to add OAuth 2.0 support for Google and GitHub"

Managing a Sprint

1. Create a new cycle:

Create a 2-week sprint called "Q1 Sprint 3" for team abc-123 starting 2024-02-01

2. List issues to find what to include:

List backlog issues for team abc-123

3. Update issues to add them to the sprint and assign:

Update issue ENG-45 to add to cycle cycle-123 and assign to user xyz-456

Tracking Progress

1. Search for issues in a specific area:

Search for issues about "authentication"

2. Get detailed information:

Get details for issue ENG-123

3. Add progress updates:

Add comment to ENG-123: "Authentication flow is complete, working on tests"

Development

Scripts

• bun run build - Build the TypeScript project

• bun run dev - Watch mode for development

• bun start - Start the MCP server

• bun run lint - Run ESLint

• bun run format - Format code with Prettier

• bun run typecheck - Type check without emitting files

Project Structure

mcp-linearapp/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── linear-client.ts      # Linear API client wrapper
│   ├── tools/                # MCP tool implementations
│   │   ├── issues.ts         # Issue-related tools
│   │   ├── projects.ts       # Project tools
│   │   ├── cycles.ts         # Cycle/sprint tools
│   │   ├── teams.ts          # Team tools
│   │   ├── labels.ts         # Label tools
│   │   └── users.ts          # User tools
│   └── schemas/              # Zod validation schemas
│       └── index.ts
├── dist/                     # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Architecture

The server is built with:

• MCP SDK: Handles the Model Context Protocol communication

• Linear SDK: Official Linear API client

• Zod: Runtime type validation and schema enforcement

• TypeScript: Type safety throughout the codebase

Key design decisions:

1. Type Safety: All inputs are validated with Zod schemas before reaching the Linear API

2. Error Handling: Comprehensive error handling with meaningful error messages

3. Modular Design: Tools are organized by domain (issues, projects, cycles, etc.)

4. Client Wrapper: LinearAPIClient provides a clean abstraction over the Linear SDK with consistent error handling and data formatting

Error Handling

The server provides clear error messages for common issues:

• Missing API Key: "LINEAR_API_KEY environment variable is required"

• Invalid Parameters: Zod validation errors with specific field information

• API Errors: Linear API errors are caught and formatted with context

• Not Found: Clear messages when issues, teams, or other resources don't exist

Rate Limiting

Linear's API has rate limits. The server doesn't implement client-side rate limiting, but:

• Uses the official Linear SDK which handles some retry logic

• Provides clear error messages when rate limits are hit

• Consider implementing delays between bulk operations

Troubleshooting

Server won't start

• Verify LINEAR_API_KEY is set in your environment

• Check that Bun version is 1.0.0 or higher (or Node.js 18.0.0+)

• Ensure bun run build completed successfully

"Invalid API key" error

• Verify your API key is correct

• Check that the key hasn't been revoked in Linear settings

• Ensure there are no extra spaces in the .env file

"Team not found" or similar errors

• Use linear_list_teams to get valid team IDs

• Use linear_list_users to get valid user IDs

• Use linear_list_projects to get valid project IDs

• Issue identifiers are case-sensitive (e.g., "ENG-123" not "eng-123")

Changes not appearing in OpenCode

• Restart OpenCode after modifying the configuration

• Check OpenCode logs for connection errors

• Verify the absolute path in the configuration is correct

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes with proper TypeScript types

4. Add/update tests if applicable

5. Run bun run lint and bun run typecheck

6. Submit a pull request

License

MIT

Acknowledgments

• Built with the Model Context Protocol SDK

• Uses the Linear SDK for API access

• Inspired by the Linear community and MCP ecosystem

Support

• Linear API Documentation: https://developers.linear.app/

• MCP Documentation: https://modelcontextprotocol.io/

• Report issues: GitHub Issues