# Linear MCP > Linear lets your AI client read, write, and manage issues directly inside Linear—no tab switching needed. You can list all teams, search for specific bugs, create new tasks with defined priorities, or add comments right from your IDE. It gives your agent full control over project metadata, allowing you to check sprint progress, view project scope, and audit issue status using natural conversation. ## Overview - **Category:** loved-by-devs - **Price:** Free - **Tags:** issue-tracking, sprint-planning, workflow-automation, task-management, team-collaboration, software-development ## Description You're talking to your agent, not logging into Linear. This server gives your AI client full control over project metadata—you can check sprint progress, view project scope, and audit issue status just by chatting with it. You don't have to switch tabs or open the app; your agent handles all the heavy lifting. **Project Discovery & Context** Need to know what teams you even got? Use `list_teams` to pull a list of every team in the organization, grabbing their unique ID and name. Want to see what projects are running across departments? Run `list_projects` for all available project containers; it'll let you limit how many results come back. If you need the deep details on one specific project, use `get_project` with a project ID. Your agent knows who you are when you connect; run `get_viewer` to check and return your current user profile data associated with the API key. This gives you immediate context about the credentials running the show. **Finding Issues & Scope** Need to find a bug or feature? You can search all Linear issues using `search_issues`. You'll get results back that include priority and assignee info, and you can even narrow that down by team. If you know the exact issue ID—like TEAM-123—you use `get_issue` to retrieve every single detail on it. Want a quick overview of all open tickets for a specific group? Run `list_issues`, which lets you filter results to show only tasks belonging to one particular team. Before creating anything, check out the available tags by running `list_labels`. This gives you a list of every label used in your workspace and their corresponding color codes. For full visibility into project structure, you can use `list_teams` to get all teams, and then follow up with `get_issue` or `search_issues` for specific work. **Making Changes & Tracking Progress** When it's time to act, your agent takes over. To start a new task, you use `create_issue`, providing the necessary team ID and title; you can even assign priority or set an assignee right out of the gate. If something changes on an existing bug—say, the status shifts or someone else gets assigned—you just hit up `update_issue` with the issue's ID to change whatever fields are needed. Need to leave a note? Use `create_comment`. You can drop a formatted comment directly onto any issue, including mentions and strikethrough text, keeping all the team context right where you are. For tracking velocity, run `list_cycles` to get a list of every sprint cycle for a team, which provides the start date, end date, and its current completion percentage. **The Bottom Line** You just tell your agent what you need—whether it's listing all teams with `list_teams`, checking on progress using `list_cycles`, or making an update with `update_issue`—and it handles the API calls. It keeps you in the chat window, letting you manage everything without ever leaving your current IDE. ## Tools ### create_comment Adds a formatted comment, including mentions and strikethrough text, to an existing Linear issue. ### create_issue Creates a brand new Linear task, requiring a team ID and title, with optional fields like priority and assignee. ### get_issue Retrieves the full details of any specific issue using its unique UUID or readable identifier (e.g., TEAM-123). ### get_project Fetches all data for a single, defined Linear project by ID. ### get_viewer Checks and returns the user profile details associated with your current API access token. ### list_cycles Lists all sprint cycles for a team, providing the start date, end date, and completion percentage. ### list_issues Retrieves a list of issues, optionally filtering results to show only tasks belonging to one specific team. ### list_labels Lists all issue labels available across your workspace, including their name and color. ### list_projects Fetches a list of all projects in the Linear workspace. You can limit the number of results returned. ### list_teams Lists every team in your organization, providing their unique ID and name for later use when querying issues or cycles. ### search_issues Searches all Linear issues by text query. You can optionally limit the search to a specific team and get priority/assignee info. ### update_issue Modifies an existing issue using its ID, allowing you to change only the fields you specify (e.g., status or assignee). ## Prompt Examples **Prompt:** ``` Show me all unresolved issues assigned to the Engineering team. ``` **Response:** ``` I've queried your Engineering team and found 7 open issues. The highest priority items are 'Fix auth token refresh bug' (ENG-142) and 'Implement pagination for API responses' (ENG-138). Would you like full details on either? ``` **Prompt:** ``` Create a new issue in the Backend team titled 'Add rate limiting to /api/search endpoint' with high priority. ``` **Response:** ``` Done! I've created issue **BE-217** titled 'Add rate limiting to /api/search endpoint' with priority High in the Backend team. You can view it at linear.app/yourco/issue/BE-217. ``` **Prompt:** ``` What's the current sprint cycle progress for the Mobile team? ``` **Response:** ``` The Mobile team's active cycle is #47 (Mar 31 — Apr 13) with 62% completion. There are 14 issues in this cycle, 5 of which are already done. Would you like the list of remaining open issues? ``` ## Capabilities ### Manage Issues You can search for existing bugs or features using `search_issues`, get full details on a single issue ID with `get_issue`, or create new ones entirely with `create_issue`. ### Update Task Metadata Modify an issue's state, assignee, or priority using the dedicated `update_issue` tool. You must provide the specific issue ID for this to work. ### Track Team Progress List all active sprint cycles (`list_cycles`) and get their current completion percentage, giving you a clear view of team velocity. ### Discover Project Scope Find out what teams exist (`list_teams`), which projects group issues across multiple departments (`list_projects`), or check the user credentials linked to your API key using `get_viewer`. ### Add Comments and Context Use `create_comment` to add formatted notes directly to an issue, keeping team context without leaving your current chat window. ## Use Cases ### The PM needs an immediate scope audit. A Product Manager needs to understand if a new feature is blocked. They run `list_projects` to get all active projects, then use `search_issues` across those project IDs with keywords like 'Auth' or 'V2'. The agent returns a list of relevant issues and their current priority, showing exactly where the roadblocks are. ### The Dev needs to update status mid-flow. A developer finishes a bug fix. Instead of navigating back to Linear, they use `update_issue` with the issue's ID and specify 'Status: Ready for Review'. They then run `create_comment` saying 'Fix pushed to staging; ready for QA review', closing the loop without leaving their coding window. ### The Manager needs a quick cycle check. It's Monday morning, and the Engineering Manager needs to know if the Mobile team is falling behind. They run `list_cycles` for that team. The agent immediately reports the active sprint number, the date range, and the current completion percentage (e.g., 62%), allowing them to call a meeting before issues pile up. ### The Planner needs to structure new work. A Product Owner has gathered requirements for next quarter's goals. They run `create_issue`, providing the required team ID, title, and setting the priority to 'High', ensuring the issue is logged correctly from day one with proper metadata. ## Benefits - Check sprint health instantly. Instead of opening Linear to review a team's progress, just ask for it using `list_cycles`. You get the start/end dates and current completion percentage in one prompt. - Audit entire feature scopes. To see all related bugs across multiple departments, use `search_issues` combined with `list_teams`, giving you visibility without navigating through project folders. - Keep context within your IDE. When reviewing a bug, running `create_comment` lets you add notes or ask questions directly to the issue thread via chat, skipping the tab switch. - Know who owns what. Need to find an assignee? Run `search_issues`, and the output shows the current assignee right away. No manual lookup required. - Manage tasks with precision. When a bug is fixed, use `update_issue` to change its status or assign it to QA—all in one go. You only provide the ID and what needs changing. ## How It Works The bottom line is: your AI client talks to Linear using structured tools, so you get answers without clicking through dashboards. 1. Subscribe to this server and provide your Linear Personal API Key. 2. Tell your AI client what you need—for example: 'What's the progress on the Mobile team sprint?' 3. The agent executes `list_cycles` or `search_issues`, retrieves the data, and gives you a clean summary. ## Frequently Asked Questions **How do I find all open issues assigned to the 'Platform' team using list_issues?** You must run `list_teams` first to get the unique Team ID for 'Platform'. Then, pass that ID into `search_issues`. This gives you a filtered list of only those issues. **What is the best way to check sprint health using list_cycles?** Run `list_cycles` and specify the Team ID. The output provides the cycle's progress percentage, start date, and end date in one data block, letting you spot delays immediately. **Can I change an issue's priority using update_issue?** Yes. You must first get the specific Issue UUID using `get_issue`. Then, use `update_issue` and specify both the UUID and the new desired priority level (e.g., 'High'). **How do I find all available projects to scope a feature?** Call `list_projects`. This function returns every active project in your workspace, allowing you to gather context and understand which teams are contributing to that scope. **How do I use `get_viewer` to verify which account my agent is operating under?** Run `get_viewer` first. This confirms the authenticated user details, so you know exactly which Linear workspace your AI client is accessing before making any changes. **When should I use `list_labels` before creating a new issue with `create_issue`?** You must run `list_labels` to pull the exact label ID. This prevents errors and ensures your agent assigns categorization tags correctly when generating a new task. **How do I use `get_issue` to verify details before running `update_issue`?** `Get_issue` pulls all current fields and metadata for an issue ID. Always run this first; it lets you confirm the assignee or priority level before committing a change with `update_issue`. **When should I use `create_comment` instead of creating a new task via `create_issue`?** Use `create_comment` when you just need to provide immediate, contextual discussion or an update. It keeps the conversation attached directly to the existing thread without generating new tasks. **How do I find my Linear Personal API Key?** Go to [**Linear Settings > API**](https://linear.app/settings/api) and click **Create API Key**. Give it a descriptive name like 'Vinkius MCP' and copy the generated key immediately — it won't be shown again. **Can I create new issues with assignees and labels?** Yes! Use the `create_issue` tool with the required `team_id` and `title` parameters. Optionally provide `assignee_id`, `priority` (0-4), `description` in Markdown and `label_ids` as a comma-separated list. The agent will return the created issue's identifier and URL. **Does the agent have access to delete issues or modify team settings?** No. This server focuses on read operations and safe mutations — creating issues, updating fields and adding comments. Destructive actions like deletion or team configuration changes are not exposed, keeping your workspace secure.