@mcp-devtools/linear

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.