Linear MCP Server

🚀 Linear MCP Server

This is a custom Linear issue tracking system adapter implemented based on TypeScript and the Model Context Protocol (MCP). This server allows AI agents to interact with the Linear platform through standard input and output, supporting operations such as creating, querying, and updating issues, teams, and projects.

🚀 Quick Start

Obtain API Key

Visit the Linear website, create a new project, and obtain the API key.

Install Dependencies

Use the Node.js package manager to install the required dependencies:

npm install @linear/sdk@37.0.0 @modelcontextprotocol/sdk@0.6.0

Run the Server

Create an index.ts file in the project root directory, add the following code, and execute it:

import { LinearMCPAdapter } from './src/adapter';

const adapter = new LinearMCPAdapter({
  token: 'your-linear-token',
  projectId: 'your-project-id'
});

adapter.start();

Then run:

npm run dev

✨ Features

Issue Management

• Create Issue: Send a POST request to the /create-issue endpoint, supporting custom titles, descriptions, priorities, and assignees.
• Query Issues: Support flexible filtering of issues by project ID, team ID, and status parameters. By default, the first 50 records are returned.
• Update Issue: Support updating all fields of an existing issue, including title, description, status, assignee, etc.

Team Management

• Get All Teams: Call the /list-teams endpoint to return information about all teams in the current workspace.

Project Management

• Get All Projects: Support filtering and querying the project list by team ID. By default, the first 50 projects are returned.

📚 Documentation

Quick Development

Execute the following command in the project root directory to start the development server and enable automatic build:

npm run dev

Automatic Rebuild

Use the following command to keep the development environment hot-reloaded:

npm run watch

Debugging Tools

Run the following commands to install debugging tools and start the debugging server:

npm install -g supergiant
supergiant start

Configuration Guide

Configure in Code

When initializing the adapter in the index.ts file, you can pass the following parameters:

const adapter = new LinearMCPAdapter({
  token: 'your-linear-token',
  projectId: 'your-project-id'
});

Configure in Environment Variables

Create a .env file in the project root directory and add the following content:

LINEAR_TOKEN=your-linear-token
LINEAR_PROJECT_ID=your-project-id

Tool Interfaces

Create Issue

The request parameter format is as follows:

{
  title: string;    // Required: Issue title
  description?: string; // Optional: Issue description
  priority?: number;    // Optional: Priority, range from 0-4
  assignee?: string;   // Optional: Assignee ID
  labels?: string[];   // Optional: Label list
}

Query Issues

The request parameter format is as follows:

{
  assignee?: string;  // Optional: Query all issues of a specified person
  status?: string;    // Optional: Filter by status (e.g., "open", "in-progress", etc.)
  first?: number;     // Optional: Limit the number of returned issues, default is 50
}

Update Issue

The request parameter format is as follows:

{
  issueId: string;   // Required: Issue ID
  title?: string;    // Optional: New title
  description?: string; // Optional: New description
  status?: string;   // Optional: New status
  assignee?: string; // Optional: New assignee
  priority?: number; // Optional: New priority
  labels?: string[]; // Optional: Update label list
}

Get Issue Details

The request parameter format is as follows:

{
  issueId: string; // Required: Issue ID
}

🔧 Technical Details

• Build Tools: Developed using TypeScript and Node.js.
• Dependency Management:
  • Linear SDK Version: 37.0.0
  • MCP SDK Version: 0.6.0
• Communication Protocol: A custom protocol based on standard input and output, compatible with the Model Context Protocol standard.

Error Handling

All API requests return structured error information in the following format:

{
  "error": {
    "code": string; // Error code
    "message": string; // Error description
  }
}

💻 Usage Examples

Example of Creating an Issue

Execute the following command in the terminal to create a new issue:

echo '{
  "title": "Test Issue Title",
  "description": "This is a test issue to verify the API functionality.",
  "priority": 2,
  "labels": ["bug", "high"]
}' | ./dist/index.js

Example of Querying Issues

Query the issue list of a specified team:

echo '{
  "assignee": "user123",
  "status": "open"
}' | ./dist/index.js

Complete Code Structure

// src/adapter.ts
export class LinearMCPAdapter {
  private token: string;
  private projectId: string;

  constructor(options: {
    token: string;
    projectId: string;
  }) {
    this.token = options.token;
    this.projectId = options.projectId;
  }

  public async createIssue(issue: CreateIssueParams): Promise<void> {
    // Implement the specific logic for creating an issue
  }

  public async getIssues(filter?: GetIssuesFilter): Promise<Issue[]> {
    // Implement the logic for getting the issue list
  }

  public async updateIssue(id: string, updates: UpdateIssueParams): Promise<void> {
    // Implement the logic for updating an issue
  }

  public async getIssue(id: string): Promise<Issue | null> {
    // Implement the logic for getting the details of a single issue
  }
}

Other Notes

• All API requests support JSON-formatted request bodies.
• Ensure that the HTTPS protocol is used for communication in the production environment.
• It is recommended to add appropriate error handling mechanisms for sensitive operations.

Project Contribution

Welcome to fork and submit Pull Requests to jointly improve the functionality of this adapter.