Skip to content

Latest commit

 

History

History
145 lines (100 loc) · 6.56 KB

README.md

File metadata and controls

145 lines (100 loc) · 6.56 KB

@mcp-devtools/linear

npm version License: MIT Status Badge

Talk to Linear - Model Context Protocol (MCP) Server for Linear integration with AI assistants.

✨ Highlights

  • 🔍 Issue Management - Create, read, update, and delete Linear issues
  • 🔄 Workflow Integration - Access workflow states, teams, and projects
  • 👥 User Management - List users and assign issues
  • 🔎 Powerful Search - Find issues using Linear's GraphQL API
  • ⚡ Fast Setup - Simple environment configuration

🚀 Quick Start

Installation

To use the Linear MCP server with Cursor IDE:

  1. Open Cursor Settings → MCP
  2. Click "Add New MCP Server"
  3. Fill in the following details:
    • Name: Linear
    • Type: command
    • Command: 
      env LINEAR_API_KEY=[YOUR_API_KEY] npx -y @mcp-devtools/linear

Required Environment Variables:

  • LINEAR_API_KEY: Your Linear API key (Create one in Linear at Settings → Security & access → Personal API keys)

Using Linear Tools

Once configured, you can interact with Linear through your AI assistant in Cursor:

# Search for issues
search_issues "bug in authentication"

# Get detailed information about a specific issue
get_issue ENG-123

# Create a new issue
create_issue teamId="TEAM_ID" title="Fix login bug" description="Users can't login properly"

# List teams
list_teams

# List workflow states for a team
list_workflow_states teamId="TEAM_ID"

📋 Tool Reference

Tool Description Parameters Aliases
search_issues Search for issues using a query string query (string), maxResults (number, optional) execute_graphql
get_issue Get detailed information about an issue issueId (string) read_issue, get_task, read_task
create_issue Create a new issue teamId (string), title (string), description (string, optional), priority (number, optional), assigneeId (string, optional), stateId (string, optional) create_task
update_issue Update an existing issue issueId (string), title (string, optional), description (string, optional), priority (number, optional), assigneeId (string, optional), stateId (string, optional) edit_issue, update_task, edit_task
delete_issue Delete an issue issueId (string) delete_task
list_teams List all teams - -
list_workflow_states List workflow states for a team teamId (string) -
list_users List all users - -
list_projects List projects maxResults (number, optional) -

🛠️ Examples

Searching for Issues

# Basic search by keyword
search_issues "authentication bug"

# Search with limited results
search_issues "priority is high" maxResults=5

# Advanced search using Linear's query syntax
search_issues "assignee:@me status:Todo"

Managing Issues

# Create an issue
create_issue teamId="TEAM_ID" title="Update documentation" description="The API documentation needs to be updated with the new endpoints"

# Update an issue
update_issue issueId="ENG-123" title="Updated title" priority=2

# Delete an issue
delete_issue issueId="ENG-123"

Team and User Management

# Get a list of all teams
list_teams

# Get workflow states for a team
list_workflow_states teamId="TEAM_ID"

# List all users
list_users

⚙️ Configuration

Environment Variables

Variable Description Required Default
LINEAR_API_KEY Your Linear API key Yes -

Using with Linear GraphQL API

The Linear MCP server uses Linear's GraphQL API. For advanced queries, you can use the execute_graphql alias, which works the same as search_issues.

🆘 Troubleshooting

Common Issues

  1. Authentication Error

    • Ensure your Linear API key is valid and has the necessary permissions
    • Check that you've correctly set the LINEAR_API_KEY environment variable

  2. Issues Not Found

    • Verify that issue identifiers are in the correct format (e.g., "ENG-123")
    • Make sure your search queries follow Linear's search syntax

  3. Permission Issues

    • Ensure your API key has permission to perform the requested actions
    • Some operations may require admin-level permissions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.