article

README

Linear MCP Server

This is a Model Context Protocol (MCP) server for Linear, allowing Claude to interact with Linear's API to manage teams, issues, projects, and cycles.

Features

linear_get_teams: Get all teams with their states and labels
linear_search_issues: Search for issues with filtering and pagination
linear_get_cycles: Get all cycles for a team
linear_get_projects: Get all projects
linear_create_issue: Create a new issue
linear_update_issue: Update an existing issue

Quick Start

For Cline MCP Marketplace users:

Install the server through the Cline MCP Marketplace
Configure your Linear credentials in the MCP configuration file
Verify the installation by testing the connection with linear_search_issues

See the detailed Installation and Verification sections below.

Installation

Clone this repository
Install dependencies:
```
npm install
```
Build the server:
```
npm run build
```

The installation process has three main steps:

Setup: Clone and build the server (steps above)
Configuration: Set up your Linear OAuth token and configure the MCP server
Verification: Test the connection to ensure it's working properly

⚠️ Your installation is not complete until you've verified the connection works!

Configuration

The server requires a Linear OAuth token to authenticate with the Linear API. You can set this token in the MCP configuration file.

Getting a Linear OAuth Token

Create a Linear OAuth application at https://linear.app/settings/api/applications
Create an OAuth Application
Name the Application Cline MCP
Set the redirect URI to http://localhost:3000/callback
Note the client ID and client secret
Create and Copy a USER based developer token

MCP Configuration

Add the following to your MCP configuration file:

{
  "mcpServers": {
    "github.com/cpropster/linear-mcp-server": {
      "command": "node",
      "args": [
        "/path/to/linear-mcp-server/build/index.js"
      ],
      "env": {
        "LINEAR_CLIENT_ID": "your-client-id",
        "LINEAR_CLIENT_SECRET": "your-client-secret",
        "LINEAR_REDIRECT_URI": "http://localhost:3000/callback",
        "LINEAR_REFRESH_TOKEN": "your-refresh-token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Replace the placeholder credentials with your actual credentials.

Verifying Installation

⚠️ IMPORTANT: Your installation is not complete until you verify that the MCP connection is working correctly.

After configuring the MCP server, you must test the connection to ensure it's working properly:

Reload the MCP configuration
Test the connection by using the linear_search_issues tool:

use_mcp_tool(
  server_name="github.com/cpropster/linear-mcp-server",
  tool_name="linear_search_issues",
  arguments={
    "first": 5
  }
)

If successful, you'll see a response like this:

{
  "issues": {
    "nodes": [
      {
        "id": "123abc",
        "title": "Example issue 1",
        "identifier": "TEAM-123",
        "description": "This is an example issue"
        // ... other issue data
      },
      // ... more issues
    ]
  }
}

If the connection is working, you'll see a list of issues from your Linear account. If you see an error, check your configuration and credentials.

Common issues:

Incorrect server path in the args field
Invalid or expired Linear tokens
Missing required environment variables
Server is disabled in the configuration

Usage

Getting Teams

Use the linear_get_teams tool to retrieve all teams:

use_mcp_tool(
  server_name="github.com/cpropster/linear-mcp-server",
  tool_name="linear_get_teams",
  arguments={}
)

Searching Issues

Use the linear_search_issues tool to search for issues:

use_mcp_tool(
  server_name="github.com/cpropster/linear-mcp-server",
  tool_name="linear_search_issues",
  arguments={
    "query": "Optional search query",
    "teamIds": ["Optional team IDs"],
    "first": 10 // Number of issues to return (default: 50)
  }
)

Getting Cycles

Use the linear_get_cycles tool to retrieve cycles for a team:

use_mcp_tool(
  server_name="github.com/cpropster/linear-mcp-server",
  tool_name="linear_get_cycles",
  arguments={
    "teamId": "required-team-id"
  }
)

Getting Projects

Use the linear_get_projects tool to retrieve projects:

use_mcp_tool(
  server_name="github.com/cpropster/linear-mcp-server",
  tool_name="linear_get_projects",
  arguments={
    "teamId": "optional-team-id",
    "first": 10 // Number of projects to return (default: 50)
  }
)

Creating Issues

Use the linear_create_issue tool to create a new issue:

use_mcp_tool(
  server_name="github.com/cpropster/linear-mcp-server",
  tool_name="linear_create_issue",
  arguments={
    "teamId": "required-team-id",
    "title": "Required issue title",
    "description": "Optional issue description",
    "assigneeId": "optional-assignee-id",
    "stateId": "optional-state-id",
    "priority": 0, // Optional priority (0-4)
    "estimate": 1, // Optional estimate
    "cycleId": "optional-cycle-id",
    "projectId": "optional-project-id",
    "labelIds": ["optional-label-ids"]
  }
)

Updating Issues

Use the linear_update_issue tool to update an existing issue:

use_mcp_tool(
  server_name="github.com/cpropster/linear-mcp-server",
  tool_name="linear_update_issue",
  arguments={
    "issueId": "required-issue-id",
    "title": "Optional new title",
    "description": "Optional new description",
    "assigneeId": "optional-assignee-id",
    "stateId": "optional-state-id",
    "priority": 0, // Optional priority (0-4)
    "estimate": 1, // Optional estimate
    "cycleId": "optional-cycle-id",
    "projectId": "optional-project-id",
    "labelIds": ["optional-label-ids"]
  }
)

Debugging

If you encounter issues during the verification step, or if the MCP connection stops working, you can use these debugging techniques:

Check MCP Configuration: Ensure your MCP configuration file has the correct server path and credentials.
Run the Test Client: Use the included test client to verify the server can connect to Linear:
```
node test-client.js
```
This will run a series of tests to verify that the server can connect to Linear and retrieve data.
Check Linear API Status: Verify that the Linear API is operational at status.linear.app.
Inspect Server Logs: If you're running the server manually, check the console output for error messages.

Development

The server is built using TypeScript and the Linear SDK. The main implementation is in src/index.ts.

To make changes to the server:

Edit the source code in src/
Build the server with npm run build
Test your changes with the test client
Update the MCP configuration to use the new build

Security Considerations

This MCP server requires access to your Linear account. To keep your data secure:

Never commit sensitive tokens: The .env file and any files containing tokens are excluded in .gitignore
Use environment variables: Always use environment variables in the MCP configuration rather than hardcoding tokens
Limit permissions: When creating a Linear OAuth application, only grant the permissions needed
Regularly rotate tokens: Periodically generate new tokens and update your configuration

The server uses the official Linear SDK and communicates with Linear's API over HTTPS, ensuring your data is transmitted securely.

License

MIT

Linear MCP服务器