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:

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

See the detailed Installation and Verification sections below.

Installation

1. Clone this repository
2. Install dependencies:

   npm install
   

3. Build the server:

   npm run build
   

The installation process has three main steps:

1. Setup: Clone and build the server (steps above)
2. Configuration: Set up your Linear OAuth token and configure the MCP server
3. 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

1. Create a Linear OAuth application at https://linear.app/settings/api/applications
2. Create an OAuth Application
3. Name the Application Cline MCP
4. Set the redirect URI to http://localhost:3000/callback
5. Note the client ID and client secret
6. 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:

1. Reload the MCP configuration
2. 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:

1. Check MCP Configuration: Ensure your MCP configuration file has the correct server path and credentials.

2. 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.

3. Check Linear API Status: Verify that the Linear API is operational at status.linear.app.

4. 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:

1. Edit the source code in src/
2. Build the server with npm run build
3. Test your changes with the test client
4. 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:

1. Never commit sensitive tokens: The .env file and any files containing tokens are excluded in .gitignore
2. Use environment variables: Always use environment variables in the MCP configuration rather than hardcoding tokens
3. Limit permissions: When creating a Linear OAuth application, only grant the permissions needed
4. 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