{"id":26913778,"url":"https://github.com/cosmix/linear-mcp","last_synced_at":"2025-04-01T16:48:26.945Z","repository":{"id":274009676,"uuid":"921619675","full_name":"cosmix/linear-mcp","owner":"cosmix","description":"A Model Context Protocol server for Linear.","archived":false,"fork":false,"pushed_at":"2025-03-22T23:17:02.000Z","size":131,"stargazers_count":20,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-23T00:18:56.951Z","etag":null,"topics":["anthropic","linear","llm","mcp"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cosmix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-24T09:43:11.000Z","updated_at":"2025-03-22T23:17:05.000Z","dependencies_parsed_at":"2025-03-07T18:23:54.067Z","dependency_job_id":"796dd585-9559-4911-b80a-85002723a3d9","html_url":"https://github.com/cosmix/linear-mcp","commit_stats":null,"previous_names":["cosmix/linear-mcp"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosmix%2Flinear-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosmix%2Flinear-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosmix%2Flinear-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cosmix%2Flinear-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cosmix","download_url":"https://codeload.github.com/cosmix/linear-mcp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246674003,"owners_count":20815667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anthropic","linear","llm","mcp"],"created_at":"2025-04-01T16:48:26.371Z","updated_at":"2025-04-01T16:48:26.927Z","avatar_url":"https://github.com/cosmix.png","language":"TypeScript","funding_links":[],"categories":["AI/ML"],"sub_categories":[],"readme":"# Linear MCP Server\n\nA Model Context Protocol (MCP) server implementation that provides access to Linear's issue tracking system through a standardized interface.\n\n## Features\n\n* Create new issues and subissues with label support\n* Retrieve the list of linear projects\n* Retrieve the project updates\n* Create a new project update with health status\n* Update existing issues with full field modification\n* Delete issue with validation\n* Self-assign issues using 'me' keyword\n* Advanced search with Linear's powerful filtering capabilities\n* Filter issues by cycle (current, next, previous, or specific cycle by UUID or number)\n* Add comments to issues with markdown support\n* Query Linear issues by ID or key with optional relationships\n* Search issues using custom queries with enhanced metadata\n* Type-safe operations using Linear's official SDK\n* Comprehensive error handling\n* Rate limit handling\n* Clean data transformation\n* Parent/child relationship tracking with team inheritance\n* Label management and synchronization\n\n## Prerequisites\n\n- [Bun](https://bun.sh) runtime (v1.0.0 or higher)\n- Linear account with API access\n\n## Environment Variables\n\n```bash\nLINEAR_API_KEY=your_api_key  # Your Linear API token\n```\n\n## Installation \u0026 Setup\n\n### 1. Clone the repository:\n\n```bash\ngit clone [repository-url]\ncd linear-mcp\n```\n\n### 2. Install dependencies and build:\n\n```bash\nbun install\nbun run build\n```\n\n### 3. Configure the MCP server:\n\nEdit the appropriate configuration file:\n\n**macOS:**\n* Cline: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`\n* Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n**Windows:**\n* Cline: `%APPDATA%\\Code\\User\\globalStorage\\saoudrizwan.claude-dev\\settings\\cline_mcp_settings.json`\n* Claude Desktop: `%APPDATA%\\Claude Desktop\\claude_desktop_config.json`\n\n**Linux:**\n* Cline: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`\n* Claude Desktop: _sadly doesn't exist yet_\n\nAdd the following configuration under the `mcpServers` object:\n\n```json\n{\n  \"mcpServers\": {\n    \"linear\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/linear-mcp/build/index.js\"],\n      \"env\": {\n        \"LINEAR_API_KEY\": \"your_api_key\"\n      }\n    }\n  }\n}\n```\n\n### 4. Restart the MCP server.\n\nWithin Cline's MCP settings, restart the MCP server. Restart Claude Desktop to load the new MCP server.\n\n## Development\n\nRun development server:\n```bash\nbun run dev\n```\n\nBuild project:\n```bash\nbun run build\n```\n\n## Available MCP Tools\n\nFor detailed usage examples of all tools, see [USAGE.md](USAGE.md).\n\n### create_issue\n\nCreate a new Linear issue or subissue.\n\nInput Schema:\n```json\n{\n  \"teamId\": \"string\",     \n  \"title\": \"string\",      \n  \"description\": \"string\",\n  \"parentId\": \"string\",   \n  \"status\": \"string\",\n  \"priority\": \"number\",   \n  \"assigneeId\": \"string | 'me'\",\n  \"labelIds\": [\"string\"]  \n}\n```\n\n### update_issue\n\nUpdate an existing Linear issue.\n\nInput Schema:\n```json\n{\n  \"issueId\": \"string\",    \n  \"title\": \"string\",\n  \"description\": \"string\",\n  \"status\": \"string\",     // Expects status NAME (e.g., \"In Progress\"). Must be valid for the issue's team.\n  \"priority\": \"number\",   // Expects 0 (None) to 4 (Low).\n  \"assigneeId\": \"string | 'me'\",\n  \"labelIds\": [\"string\"],\n  \"cycleId\": \"string\"\n}\n```\n\n### get_issue\n\nGet detailed information about a specific Linear issue with optional relationships.\n\nInput Schema:\n```json\n{\n  \"issueId\": \"string\",\n  \"includeRelationships\": \"boolean\"  \n}\n```\n\n### search_issues\n\nSearch for Linear issues using a query string and advanced filters. Supports Linear's powerful filtering capabilities.\n\nInput Schema:\n```json\n{\n  \"query\": \"string\",\n  \"includeRelationships\": \"boolean\",\n  \"filter\": {\n    \"title\": { \"contains\": \"string\", \"eq\": \"string\", ... },\n    \"description\": { \"contains\": \"string\", \"eq\": \"string\", ... },\n    \"priority\": { \"gte\": \"number\", \"lt\": \"number\", ... },\n    \"estimate\": { \"eq\": \"number\", \"in\": [\"number\"], ... },\n    \"dueDate\": { \"lt\": \"string\", \"gt\": \"string\", ... },\n    \"createdAt\": { \"gt\": \"P2W\", \"lt\": \"2024-01-01\", ... },\n    \"updatedAt\": { \"gt\": \"P1M\", ... },\n    \"completedAt\": { \"null\": true, ... },\n    \"assignee\": { \"id\": { \"eq\": \"string\" }, \"name\": { \"contains\": \"string\" } },\n    \"creator\": { \"id\": { \"eq\": \"string\" }, \"name\": { \"contains\": \"string\" } },\n    \"team\": { \"id\": { \"eq\": \"string\" }, \"key\": { \"eq\": \"string\" } },\n    \"state\": { \"type\": { \"eq\": \"started\" }, \"name\": { \"eq\": \"string\" } },\n    \"labels\": { \"name\": { \"in\": [\"string\"] }, \"every\": { \"name\": { \"eq\": \"string\" } } },\n    \"project\": { \"id\": { \"eq\": \"string\" }, \"name\": { \"contains\": \"string\" } },\n    \"and\": [{ /* filters */ }],\n    \"or\": [{ /* filters */ }],\n    \"assignedTo\": \"string | 'me'\",\n    \"createdBy\": \"string | 'me'\"\n  },\n  \"projectId\": \"string\",\n  \"projectName\": \"string\"\n}\n```\n\nSupported Comparators:\n- String fields: `eq`, `neq`, `in`, `nin`, `contains`, `startsWith`, `endsWith` (plus case-insensitive variants)\n- Number fields: `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `in`, `nin`\n- Date fields: `eq`, `neq`, `lt`, `lte`, `gt`, `gte` (supports ISO 8601 durations)\n\n### get_teams\n\nGet a list of Linear teams with optional name/key filtering.\n\nInput Schema:\n```json\n{\n  \"nameFilter\": \"string\"  \n}\n```\n\n### delete_issue\n\nDelete an existing Linear issue.\n\nInput Schema:\n```json\n{\n  \"issueId\": \"string\"\n}\n```\n\n### create_comment\n\nCreate a new comment on a Linear issue.\n\nInput Schema:\n```json\n{\n  \"issueId\": \"string\",\n  \"body\": \"string\"\n}\n```\n\n### get_projects\n\nGet a list of Linear projects with optional name filtering and pagination.\n\nInput Schema:\n```json\n{\n  \"nameFilter\": \"string\",\n  \"includeArchived\": \"boolean\",\n  \"first\": \"number\",\n  \"after\": \"string\"\n}\n```\n\n### get_project_updates\n\nGet project updates for a given project ID with optional filtering parameters.\n\nInput Schema:\n```json\n{\n  \"projectId\": \"string\",\n  \"includeArchived\": \"boolean\",\n  \"first\": \"number\",\n  \"after\": \"string\",\n  \"createdAfter\": \"string\",\n  \"createdBefore\": \"string\",\n  \"userId\": \"string | 'me'\",\n  \"health\": \"string\"\n}\n```\n\n### create_project_update\n\nCreate a new update for a Linear project.\n\nInput Schema:\n```json\n{\n  \"projectId\": \"string\",\n  \"body\": \"string\",\n  \"health\": \"onTrack | atRisk | offTrack\",\n  \"isDiffHidden\": \"boolean\"\n}\n```\n\n## Technical Details\n\n* Built with TypeScript in strict mode\n* Uses Linear's official SDK (@linear/sdk)\n* Uses MCP SDK (@modelcontextprotocol/sdk 1.4.0)\n* Authentication via API tokens\n* Comprehensive error handling\n* Rate limiting considerations\n* Bun runtime for improved performance\n* ESM modules throughout\n* Vite build system\n* Type-safe operations\n* Data cleaning features:\n  * Issue mention extraction (ABC-123 format)\n  * User mention extraction (@username format)\n  * Markdown content cleaning\n  * Content optimization for AI context\n* Self-assignment support:\n  * Automatic current user resolution\n  * 'me' keyword support in create/update operations\n  * Efficient user ID caching\n* Advanced search capabilities:\n  * Comprehensive filtering with Linear's API\n  * Support for all field comparators\n  * Relationship filtering\n  * Logical operators (and, or)\n  * Relative date filtering\n  * Filter by assignee/creator (including self)\n  * Support for specific user IDs\n  * Project filtering by ID or name\n  * Efficient query optimization\n* Project management features:\n  * Project listing with filtering and pagination\n  * Project update creation with health status tracking\n  * Project update retrieval with filtering options\n\n## Error Handling\n\nThe server implements a comprehensive error handling strategy:\n\n* Network error detection and appropriate messaging\n* HTTP status code handling\n* Detailed error messages with status codes\n* Error details logging to console\n* Input validation for all parameters\n* Label validation and synchronization\n* Safe error propagation through MCP protocol\n* Rate limit detection and handling\n* Authentication error handling\n* Invalid query handling\n* Team inheritance validation for subissues\n* User resolution validation\n* Search filter validation\n\n## LICENCE\n\nThis project is licensed under the MIT License - see the [LICENCE](LICENCE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosmix%2Flinear-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcosmix%2Flinear-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosmix%2Flinear-mcp/lists"}