|
| 1 | +# @mcp-devtools/linear |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +Talk to Linear - Model Context Protocol (MCP) Server for Linear integration with AI assistants. |
| 8 | + |
| 9 | +## ✨ Highlights |
| 10 | + |
| 11 | +- 🔍 **Issue Management** - Create, read, update, and delete Linear issues |
| 12 | +- 🔄 **Workflow Integration** - Access workflow states, teams, and projects |
| 13 | +- 👥 **User Management** - List users and assign issues |
| 14 | +- 🔎 **Powerful Search** - Find issues using Linear's GraphQL API |
| 15 | +- ⚡ **Fast Setup** - Simple environment configuration |
| 16 | + |
| 17 | +## 🚀 Quick Start |
| 18 | + |
| 19 | +### Installation |
| 20 | + |
| 21 | +To use the Linear MCP server with Cursor IDE: |
| 22 | + |
| 23 | +1. Open Cursor Settings → MCP |
| 24 | +2. Click "Add New MCP Server" |
| 25 | +3. Fill in the following details: |
| 26 | + - **Name**: `Linear` |
| 27 | + - **Type**: `command` |
| 28 | + - **Command**: |
| 29 | + ``` |
| 30 | + env LINEAR_API_KEY=[YOUR_API_KEY] npx -y @mcp-devtools/linear |
| 31 | + ``` |
| 32 | +
|
| 33 | +> **Required Environment Variables**: |
| 34 | +> |
| 35 | +> - `LINEAR_API_KEY`: Your Linear API key (Create one in Linear at Settings → Security & access → Personal API keys) |
| 36 | +
|
| 37 | +### Using Linear Tools |
| 38 | +
|
| 39 | +Once configured, you can interact with Linear through your AI assistant in Cursor: |
| 40 | +
|
| 41 | +``` |
| 42 | +# Search for issues |
| 43 | +search_issues "bug in authentication" |
| 44 | + |
| 45 | +# Get detailed information about a specific issue |
| 46 | +get_issue ENG-123 |
| 47 | + |
| 48 | +# Create a new issue |
| 49 | +create_issue teamId="TEAM_ID" title="Fix login bug" description="Users can't login properly" |
| 50 | + |
| 51 | +# List teams |
| 52 | +list_teams |
| 53 | + |
| 54 | +# List workflow states for a team |
| 55 | +list_workflow_states teamId="TEAM_ID" |
| 56 | +``` |
| 57 | +
|
| 58 | +## 📋 Tool Reference |
| 59 | +
|
| 60 | +| Tool | Description | Parameters | Aliases | |
| 61 | +| ---------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- | |
| 62 | +| `search_issues` | Search for issues using a query string | `query` (string), `maxResults` (number, optional) | `execute_graphql` | |
| 63 | +| `get_issue` | Get detailed information about an issue | `issueId` (string) | `read_issue`, `get_task`, `read_task` | |
| 64 | +| `create_issue` | Create a new issue | `teamId` (string), `title` (string), `description` (string, optional), `priority` (number, optional), `assigneeId` (string, optional), `stateId` (string, optional) | `create_task` | |
| 65 | +| `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` | |
| 66 | +| `delete_issue` | Delete an issue | `issueId` (string) | `delete_task` | |
| 67 | +| `list_teams` | List all teams | - | - | |
| 68 | +| `list_workflow_states` | List workflow states for a team | `teamId` (string) | - | |
| 69 | +| `list_users` | List all users | - | - | |
| 70 | +| `list_projects` | List projects | `maxResults` (number, optional) | - | |
| 71 | +
|
| 72 | +## 🛠️ Examples |
| 73 | +
|
| 74 | +### Searching for Issues |
| 75 | +
|
| 76 | +``` |
| 77 | +# Basic search by keyword |
| 78 | +search_issues "authentication bug" |
| 79 | + |
| 80 | +# Search with limited results |
| 81 | +search_issues "priority is high" maxResults=5 |
| 82 | + |
| 83 | +# Advanced search using Linear's query syntax |
| 84 | +search_issues "assignee:@me status:Todo" |
| 85 | +``` |
| 86 | +
|
| 87 | +### Managing Issues |
| 88 | +
|
| 89 | +``` |
| 90 | +# Create an issue |
| 91 | +create_issue teamId="TEAM_ID" title="Update documentation" description="The API documentation needs to be updated with the new endpoints" |
| 92 | + |
| 93 | +# Update an issue |
| 94 | +update_issue issueId="ENG-123" title="Updated title" priority=2 |
| 95 | + |
| 96 | +# Delete an issue |
| 97 | +delete_issue issueId="ENG-123" |
| 98 | +``` |
| 99 | +
|
| 100 | +### Team and User Management |
| 101 | +
|
| 102 | +``` |
| 103 | +# Get a list of all teams |
| 104 | +list_teams |
| 105 | + |
| 106 | +# Get workflow states for a team |
| 107 | +list_workflow_states teamId="TEAM_ID" |
| 108 | + |
| 109 | +# List all users |
| 110 | +list_users |
| 111 | +``` |
| 112 | +
|
| 113 | +## ⚙️ Configuration |
| 114 | +
|
| 115 | +### Environment Variables |
| 116 | +
|
| 117 | +| Variable | Description | Required | Default | |
| 118 | +| ---------------- | ------------------- | -------- | ------- | |
| 119 | +| `LINEAR_API_KEY` | Your Linear API key | Yes | - | |
| 120 | +
|
| 121 | +### Using with Linear GraphQL API |
| 122 | +
|
| 123 | +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`. |
| 124 | +
|
| 125 | +## 🆘 Troubleshooting |
| 126 | +
|
| 127 | +### Common Issues |
| 128 | +
|
| 129 | +1. **Authentication Error** |
| 130 | +
|
| 131 | + - Ensure your Linear API key is valid and has the necessary permissions |
| 132 | + - Check that you've correctly set the `LINEAR_API_KEY` environment variable |
| 133 | +
|
| 134 | +2. **Issues Not Found** |
| 135 | +
|
| 136 | + - Verify that issue identifiers are in the correct format (e.g., "ENG-123") |
| 137 | + - Make sure your search queries follow Linear's search syntax |
| 138 | +
|
| 139 | +3. **Permission Issues** |
| 140 | + - Ensure your API key has permission to perform the requested actions |
| 141 | + - Some operations may require admin-level permissions |
| 142 | +
|
| 143 | +## 📄 License |
| 144 | +
|
| 145 | +This project is licensed under the MIT License - see the [LICENSE](../../LICENSE) file for details. |
0 commit comments