├── .gitignore ├── LICENSE ├── README.md ├── index.ts ├── package-lock.json ├── package.json └── tsconfig.json /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | build 3 | .env 4 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2024 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Linear MCP Server 2 | 3 | [![npm version](https://img.shields.io/npm/v/linear-mcp-server.svg)](https://www.npmjs.com/package/linear-mcp-server) [![smithery badge](https://smithery.ai/badge/linear-mcp-server)](https://smithery.ai/server/linear-mcp-server) 4 | 5 | **IMPORTANT NOTE:** This MCP Server is now deprecated and is no longer being maintained. I recommend you use the official Linear remote MCP server here: https://linear.app/changelog/2025-05-01-mcp (https://mcp.linear.app/sse) 6 | 7 | A [Model Context Protocol](https://github.com/modelcontextprotocol) server for the [Linear API](https://developers.linear.app/docs/graphql/working-with-the-graphql-api). 8 | 9 | This server provides integration with Linear's issue tracking system through MCP, allowing LLMs to interact with Linear issues. 10 | 11 | ## Installation 12 | 13 | ### Automatic Installation 14 | 15 | To install the Linear MCP server for Claude Desktop automatically via [Smithery](https://smithery.ai/protocol/linear-mcp-server): 16 | 17 | ```bash 18 | npx @smithery/cli install linear-mcp-server --client claude 19 | ``` 20 | 21 | ### Manual Installation 22 | 23 | 1. Create or get a Linear API key for your team: [https://linear.app/YOUR-TEAM/settings/api](https://linear.app/YOUR-TEAM/settings/api) 24 | 25 | 2. Add server config to Claude Desktop: 26 | - MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json` 27 | 28 | ```json 29 | { 30 | "mcpServers": { 31 | "linear": { 32 | "command": "npx", 33 | "args": [ 34 | "-y", 35 | "linear-mcp-server" 36 | ], 37 | "env": { 38 | "LINEAR_API_KEY": "your_linear_api_key_here" 39 | } 40 | } 41 | } 42 | } 43 | ``` 44 | 45 | ## Components 46 | 47 | ### Tools 48 | 49 | 1. **`linear_create_issue`**: Create a new Linear issues 50 | - Required inputs: 51 | - `title` (string): Issue title 52 | - `teamId` (string): Team ID to create issue in 53 | - Optional inputs: 54 | - `description` (string): Issue description (markdown supported) 55 | - `priority` (number, 0-4): Priority level (1=urgent, 4=low) 56 | - `status` (string): Initial status name 57 | 58 | 2. **`linear_update_issue`**: Update existing issues 59 | - Required inputs: 60 | - `id` (string): Issue ID to update 61 | - Optional inputs: 62 | - `title` (string): New title 63 | - `description` (string): New description 64 | - `priority` (number, 0-4): New priority 65 | - `status` (string): New status name 66 | 67 | 3. **`linear_search_issues`**: Search issues with flexible filtering 68 | - Optional inputs: 69 | - `query` (string): Text to search in title/description 70 | - `teamId` (string): Filter by team 71 | - `status` (string): Filter by status 72 | - `assigneeId` (string): Filter by assignee 73 | - `labels` (string[]): Filter by labels 74 | - `priority` (number): Filter by priority 75 | - `limit` (number, default: 10): Max results 76 | 77 | 4. **`linear_get_user_issues`**: Get issues assigned to a user 78 | - Optional inputs: 79 | - `userId` (string): User ID (omit for authenticated user) 80 | - `includeArchived` (boolean): Include archived issues 81 | - `limit` (number, default: 50): Max results 82 | 83 | 5. **`linear_add_comment`**: Add comments to issues 84 | - Required inputs: 85 | - `issueId` (string): Issue ID to comment on 86 | - `body` (string): Comment text (markdown supported) 87 | - Optional inputs: 88 | - `createAsUser` (string): Custom username 89 | - `displayIconUrl` (string): Custom avatar URL 90 | 91 | ### Resources 92 | 93 | - `linear-issue:///{issueId}` - View individual issue details 94 | - `linear-team:///{teamId}/issues` - View team issues 95 | - `linear-user:///{userId}/assigned` - View user's assigned issues 96 | - `linear-organization:` - View organization info 97 | - `linear-viewer:` - View current user context 98 | 99 | ## Usage examples 100 | 101 | Some example prompts you can use with Claude Desktop to interact with Linear: 102 | 103 | 1. "Show me all my high-**priority** issues" → execute the `search_issues` tool and/or `linear-user:///{userId}/assigned` to find issues assigned to you with priority 1 104 | 105 | 2. "Based on what I've told you about this bug already, make a bug report for the authentication system" → use `create_issue` to create a new high-priority issue with appropriate details and status tracking 106 | 107 | 3. "Find all in progress frontend tasks" → use `search_issues` to locate frontend-related issues with in progress task 108 | 109 | 4. "Give me a summary of recent updates on the issues for mobile app development" → use `search_issues` to identify the relevant issue(s), then `linear-issue:///{issueId}` fetch the issue details and show recent activity and comments 110 | 111 | 5. "What's the current workload for the mobile team?" → combine `linear-team:///{teamId}/issues` and `search_issues` to analyze issue distribution and priorities across the mobile team 112 | 113 | ## Development 114 | 115 | 1. Install dependencies: 116 | 117 | ```bash 118 | npm install 119 | ``` 120 | 121 | 1. Configure Linear API key in `.env`: 122 | 123 | ```bash 124 | LINEAR_API_KEY=your_api_key_here 125 | ``` 126 | 127 | 1. Build the server: 128 | 129 | ```bash 130 | npm run build 131 | ``` 132 | 133 | For development with auto-rebuild: 134 | 135 | ```bash 136 | npm run watch 137 | ``` 138 | 139 | ## License 140 | 141 | This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository. 142 | -------------------------------------------------------------------------------- /index.ts: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env node 2 | 3 | import { LinearClient, LinearDocument, Issue, User, Team, WorkflowState, IssueLabel } from "@linear/sdk"; 4 | import { Server } from "@modelcontextprotocol/sdk/server/index.js"; 5 | import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; 6 | import { 7 | CallToolRequest, 8 | CallToolRequestSchema, 9 | ListResourcesRequestSchema, 10 | ListToolsRequestSchema, 11 | ReadResourceRequestSchema, 12 | ListResourceTemplatesRequestSchema, 13 | ListPromptsRequestSchema, 14 | GetPromptRequestSchema, 15 | Tool, 16 | ResourceTemplate, 17 | Prompt, 18 | } from "@modelcontextprotocol/sdk/types.js"; 19 | import dotenv from "dotenv"; 20 | import { z } from 'zod'; 21 | 22 | interface CreateIssueArgs { 23 | title: string; 24 | teamId: string; 25 | description?: string; 26 | priority?: number; 27 | status?: string; 28 | } 29 | 30 | interface UpdateIssueArgs { 31 | id: string; 32 | title?: string; 33 | description?: string; 34 | priority?: number; 35 | status?: string; 36 | } 37 | 38 | interface SearchIssuesArgs { 39 | query?: string; 40 | teamId?: string; 41 | limit?: number; 42 | status?: string; 43 | assigneeId?: string; 44 | labels?: string[]; 45 | priority?: number; 46 | estimate?: number; 47 | includeArchived?: boolean; 48 | } 49 | 50 | interface GetUserIssuesArgs { 51 | userId?: string; 52 | includeArchived?: boolean; 53 | limit?: number; 54 | } 55 | 56 | interface AddCommentArgs { 57 | issueId: string; 58 | body: string; 59 | createAsUser?: string; 60 | displayIconUrl?: string; 61 | } 62 | 63 | interface RateLimiterMetrics { 64 | totalRequests: number; 65 | requestsInLastHour: number; 66 | averageRequestTime: number; 67 | queueLength: number; 68 | lastRequestTime: number; 69 | } 70 | 71 | interface LinearIssueResponse { 72 | identifier: string; 73 | title: string; 74 | priority: number | null; 75 | status: string | null; 76 | stateName?: string; 77 | url: string; 78 | } 79 | 80 | class RateLimiter { 81 | public readonly requestsPerHour = 1400; 82 | private queue: (() => Promise)[] = []; 83 | private processing = false; 84 | private lastRequestTime = 0; 85 | private readonly minDelayMs = 3600000 / this.requestsPerHour; 86 | private requestTimes: number[] = []; 87 | private requestTimestamps: number[] = []; 88 | 89 | async enqueue(fn: () => Promise, operation?: string): Promise { 90 | const startTime = Date.now(); 91 | const queuePosition = this.queue.length; 92 | 93 | console.error(`[Linear API] Enqueueing request${operation ? ` for ${operation}` : ''} (Queue position: ${queuePosition})`); 94 | 95 | return new Promise((resolve, reject) => { 96 | this.queue.push(async () => { 97 | try { 98 | console.error(`[Linear API] Starting request${operation ? ` for ${operation}` : ''}`); 99 | const result = await fn(); 100 | const endTime = Date.now(); 101 | const duration = endTime - startTime; 102 | 103 | console.error(`[Linear API] Completed request${operation ? ` for ${operation}` : ''} (Duration: ${duration}ms)`); 104 | this.trackRequest(startTime, endTime, operation); 105 | resolve(result); 106 | } catch (error) { 107 | console.error(`[Linear API] Error in request${operation ? ` for ${operation}` : ''}: `, error); 108 | reject(error); 109 | } 110 | }); 111 | this.processQueue(); 112 | }); 113 | } 114 | 115 | private async processQueue() { 116 | if (this.processing || this.queue.length === 0) return; 117 | this.processing = true; 118 | 119 | while (this.queue.length > 0) { 120 | const now = Date.now(); 121 | const timeSinceLastRequest = now - this.lastRequestTime; 122 | 123 | const requestsInLastHour = this.requestTimestamps.filter(t => t > now - 3600000).length; 124 | if (requestsInLastHour >= this.requestsPerHour * 0.9 && timeSinceLastRequest < this.minDelayMs) { 125 | const waitTime = this.minDelayMs - timeSinceLastRequest; 126 | await new Promise(resolve => setTimeout(resolve, waitTime)); 127 | } 128 | 129 | const fn = this.queue.shift(); 130 | if (fn) { 131 | this.lastRequestTime = Date.now(); 132 | await fn(); 133 | } 134 | } 135 | 136 | this.processing = false; 137 | } 138 | 139 | async batch(items: any[], batchSize: number, fn: (item: any) => Promise, operation?: string): Promise { 140 | const batches = []; 141 | for (let i = 0; i < items.length; i += batchSize) { 142 | const batch = items.slice(i, i + batchSize); 143 | batches.push(Promise.all( 144 | batch.map(item => this.enqueue(() => fn(item), operation)) 145 | )); 146 | } 147 | 148 | const results = await Promise.all(batches); 149 | return results.flat(); 150 | } 151 | 152 | private trackRequest(startTime: number, endTime: number, operation?: string) { 153 | const duration = endTime - startTime; 154 | this.requestTimes.push(duration); 155 | this.requestTimestamps.push(startTime); 156 | 157 | // Keep only last hour of requests 158 | const oneHourAgo = Date.now() - 3600000; 159 | this.requestTimestamps = this.requestTimestamps.filter(t => t > oneHourAgo); 160 | this.requestTimes = this.requestTimes.slice(-this.requestTimestamps.length); 161 | } 162 | 163 | getMetrics(): RateLimiterMetrics { 164 | const now = Date.now(); 165 | const oneHourAgo = now - 3600000; 166 | const recentRequests = this.requestTimestamps.filter(t => t > oneHourAgo); 167 | 168 | return { 169 | totalRequests: this.requestTimestamps.length, 170 | requestsInLastHour: recentRequests.length, 171 | averageRequestTime: this.requestTimes.length > 0 172 | ? this.requestTimes.reduce((a, b) => a + b, 0) / this.requestTimes.length 173 | : 0, 174 | queueLength: this.queue.length, 175 | lastRequestTime: this.lastRequestTime 176 | }; 177 | } 178 | } 179 | 180 | class LinearMCPClient { 181 | private client: LinearClient; 182 | public readonly rateLimiter: RateLimiter; 183 | 184 | constructor(apiKey: string) { 185 | if (!apiKey) throw new Error("LINEAR_API_KEY environment variable is required"); 186 | this.client = new LinearClient({ apiKey }); 187 | this.rateLimiter = new RateLimiter(); 188 | } 189 | 190 | private async getIssueDetails(issue: Issue) { 191 | const [statePromise, assigneePromise, teamPromise] = [ 192 | issue.state, 193 | issue.assignee, 194 | issue.team 195 | ]; 196 | 197 | const [state, assignee, team] = await Promise.all([ 198 | this.rateLimiter.enqueue(async () => statePromise ? await statePromise : null), 199 | this.rateLimiter.enqueue(async () => assigneePromise ? await assigneePromise : null), 200 | this.rateLimiter.enqueue(async () => teamPromise ? await teamPromise : null) 201 | ]); 202 | 203 | return { 204 | state, 205 | assignee, 206 | team 207 | }; 208 | } 209 | 210 | private addMetricsToResponse(response: any) { 211 | const metrics = this.rateLimiter.getMetrics(); 212 | return { 213 | ...response, 214 | metadata: { 215 | ...response.metadata, 216 | apiMetrics: { 217 | requestsInLastHour: metrics.requestsInLastHour, 218 | remainingRequests: this.rateLimiter.requestsPerHour - metrics.requestsInLastHour, 219 | averageRequestTime: `${Math.round(metrics.averageRequestTime)}ms`, 220 | queueLength: metrics.queueLength, 221 | lastRequestTime: new Date(metrics.lastRequestTime).toISOString() 222 | } 223 | } 224 | }; 225 | } 226 | 227 | async listIssues() { 228 | const result = await this.rateLimiter.enqueue( 229 | () => this.client.issues({ 230 | first: 50, 231 | orderBy: LinearDocument.PaginationOrderBy.UpdatedAt 232 | }), 233 | 'listIssues' 234 | ); 235 | 236 | const issuesWithDetails = await this.rateLimiter.batch( 237 | result.nodes, 238 | 5, 239 | async (issue) => { 240 | const details = await this.getIssueDetails(issue); 241 | return { 242 | uri: `linear-issue:///${issue.id}`, 243 | mimeType: "application/json", 244 | name: issue.title, 245 | description: `Linear issue ${issue.identifier}: ${issue.title}`, 246 | metadata: { 247 | identifier: issue.identifier, 248 | priority: issue.priority, 249 | status: details.state ? await details.state.name : undefined, 250 | assignee: details.assignee ? await details.assignee.name : undefined, 251 | team: details.team ? await details.team.name : undefined, 252 | } 253 | }; 254 | }, 255 | 'getIssueDetails' 256 | ); 257 | 258 | return this.addMetricsToResponse(issuesWithDetails); 259 | } 260 | 261 | async getIssue(issueId: string) { 262 | const result = await this.rateLimiter.enqueue(() => this.client.issue(issueId)); 263 | if (!result) throw new Error(`Issue ${issueId} not found`); 264 | 265 | const details = await this.getIssueDetails(result); 266 | 267 | return this.addMetricsToResponse({ 268 | id: result.id, 269 | identifier: result.identifier, 270 | title: result.title, 271 | description: result.description, 272 | priority: result.priority, 273 | status: details.state?.name, 274 | assignee: details.assignee?.name, 275 | team: details.team?.name, 276 | url: result.url 277 | }); 278 | } 279 | 280 | async createIssue(args: CreateIssueArgs) { 281 | const issuePayload = await this.client.createIssue({ 282 | title: args.title, 283 | teamId: args.teamId, 284 | description: args.description, 285 | priority: args.priority, 286 | stateId: args.status 287 | }); 288 | 289 | const issue = await issuePayload.issue; 290 | if (!issue) throw new Error("Failed to create issue"); 291 | return issue; 292 | } 293 | 294 | async updateIssue(args: UpdateIssueArgs) { 295 | const issue = await this.client.issue(args.id); 296 | if (!issue) throw new Error(`Issue ${args.id} not found`); 297 | 298 | const updatePayload = await issue.update({ 299 | title: args.title, 300 | description: args.description, 301 | priority: args.priority, 302 | stateId: args.status 303 | }); 304 | 305 | const updatedIssue = await updatePayload.issue; 306 | if (!updatedIssue) throw new Error("Failed to update issue"); 307 | return updatedIssue; 308 | } 309 | 310 | async searchIssues(args: SearchIssuesArgs) { 311 | const result = await this.rateLimiter.enqueue(() => 312 | this.client.issues({ 313 | filter: this.buildSearchFilter(args), 314 | first: args.limit || 10, 315 | includeArchived: args.includeArchived 316 | }) 317 | ); 318 | 319 | const issuesWithDetails = await this.rateLimiter.batch(result.nodes, 5, async (issue) => { 320 | const [state, assignee, labels] = await Promise.all([ 321 | this.rateLimiter.enqueue(() => issue.state) as Promise, 322 | this.rateLimiter.enqueue(() => issue.assignee) as Promise, 323 | this.rateLimiter.enqueue(() => issue.labels()) as Promise<{ nodes: IssueLabel[] }> 324 | ]); 325 | 326 | return { 327 | id: issue.id, 328 | identifier: issue.identifier, 329 | title: issue.title, 330 | description: issue.description, 331 | priority: issue.priority, 332 | estimate: issue.estimate, 333 | status: state?.name || null, 334 | assignee: assignee?.name || null, 335 | labels: labels?.nodes?.map((label: IssueLabel) => label.name) || [], 336 | url: issue.url 337 | }; 338 | }); 339 | 340 | return this.addMetricsToResponse(issuesWithDetails); 341 | } 342 | 343 | async getUserIssues(args: GetUserIssuesArgs) { 344 | try { 345 | const user = args.userId && typeof args.userId === 'string' ? 346 | await this.rateLimiter.enqueue(() => this.client.user(args.userId as string)) : 347 | await this.rateLimiter.enqueue(() => this.client.viewer); 348 | 349 | const result = await this.rateLimiter.enqueue(() => user.assignedIssues({ 350 | first: args.limit || 50, 351 | includeArchived: args.includeArchived 352 | })); 353 | 354 | if (!result?.nodes) { 355 | return this.addMetricsToResponse([]); 356 | } 357 | 358 | const issuesWithDetails = await this.rateLimiter.batch( 359 | result.nodes, 360 | 5, 361 | async (issue) => { 362 | const state = await this.rateLimiter.enqueue(() => issue.state) as WorkflowState; 363 | return { 364 | id: issue.id, 365 | identifier: issue.identifier, 366 | title: issue.title, 367 | description: issue.description, 368 | priority: issue.priority, 369 | stateName: state?.name || 'Unknown', 370 | url: issue.url 371 | }; 372 | }, 373 | 'getUserIssues' 374 | ); 375 | 376 | return this.addMetricsToResponse(issuesWithDetails); 377 | } catch (error) { 378 | console.error(`Error in getUserIssues: ${error}`); 379 | throw error; 380 | } 381 | } 382 | 383 | async addComment(args: AddCommentArgs) { 384 | const commentPayload = await this.client.createComment({ 385 | issueId: args.issueId, 386 | body: args.body, 387 | createAsUser: args.createAsUser, 388 | displayIconUrl: args.displayIconUrl 389 | }); 390 | 391 | const comment = await commentPayload.comment; 392 | if (!comment) throw new Error("Failed to create comment"); 393 | 394 | const issue = await comment.issue; 395 | return { 396 | comment, 397 | issue 398 | }; 399 | } 400 | 401 | async getTeamIssues(teamId: string) { 402 | const team = await this.rateLimiter.enqueue(() => this.client.team(teamId)); 403 | if (!team) throw new Error(`Team ${teamId} not found`); 404 | 405 | const { nodes: issues } = await this.rateLimiter.enqueue(() => team.issues()); 406 | 407 | const issuesWithDetails = await this.rateLimiter.batch(issues, 5, async (issue) => { 408 | const statePromise = issue.state; 409 | const assigneePromise = issue.assignee; 410 | 411 | const [state, assignee] = await Promise.all([ 412 | this.rateLimiter.enqueue(async () => statePromise ? await statePromise : null), 413 | this.rateLimiter.enqueue(async () => assigneePromise ? await assigneePromise : null) 414 | ]); 415 | 416 | return { 417 | id: issue.id, 418 | identifier: issue.identifier, 419 | title: issue.title, 420 | description: issue.description, 421 | priority: issue.priority, 422 | status: state?.name, 423 | assignee: assignee?.name, 424 | url: issue.url 425 | }; 426 | }); 427 | 428 | return this.addMetricsToResponse(issuesWithDetails); 429 | } 430 | 431 | async getViewer() { 432 | const viewer = await this.client.viewer; 433 | const [teams, organization] = await Promise.all([ 434 | viewer.teams(), 435 | this.client.organization 436 | ]); 437 | 438 | return this.addMetricsToResponse({ 439 | id: viewer.id, 440 | name: viewer.name, 441 | email: viewer.email, 442 | admin: viewer.admin, 443 | teams: teams.nodes.map(team => ({ 444 | id: team.id, 445 | name: team.name, 446 | key: team.key 447 | })), 448 | organization: { 449 | id: organization.id, 450 | name: organization.name, 451 | urlKey: organization.urlKey 452 | } 453 | }); 454 | } 455 | 456 | async getOrganization() { 457 | const organization = await this.client.organization; 458 | const [teams, users] = await Promise.all([ 459 | organization.teams(), 460 | organization.users() 461 | ]); 462 | 463 | return this.addMetricsToResponse({ 464 | id: organization.id, 465 | name: organization.name, 466 | urlKey: organization.urlKey, 467 | teams: teams.nodes.map(team => ({ 468 | id: team.id, 469 | name: team.name, 470 | key: team.key 471 | })), 472 | users: users.nodes.map(user => ({ 473 | id: user.id, 474 | name: user.name, 475 | email: user.email, 476 | admin: user.admin, 477 | active: user.active 478 | })) 479 | }); 480 | } 481 | 482 | private buildSearchFilter(args: SearchIssuesArgs): any { 483 | const filter: any = {}; 484 | 485 | if (args.query) { 486 | filter.or = [ 487 | { title: { contains: args.query } }, 488 | { description: { contains: args.query } } 489 | ]; 490 | } 491 | 492 | if (args.teamId) { 493 | filter.team = { id: { eq: args.teamId } }; 494 | } 495 | 496 | if (args.status) { 497 | filter.state = { name: { eq: args.status } }; 498 | } 499 | 500 | if (args.assigneeId) { 501 | filter.assignee = { id: { eq: args.assigneeId } }; 502 | } 503 | 504 | if (args.labels && args.labels.length > 0) { 505 | filter.labels = { 506 | some: { 507 | name: { in: args.labels } 508 | } 509 | }; 510 | } 511 | 512 | if (args.priority) { 513 | filter.priority = { eq: args.priority }; 514 | } 515 | 516 | if (args.estimate) { 517 | filter.estimate = { eq: args.estimate }; 518 | } 519 | 520 | return filter; 521 | } 522 | } 523 | 524 | const createIssueTool: Tool = { 525 | name: "linear_create_issue", 526 | description: "Creates a new Linear issue with specified details. Use this to create tickets for tasks, bugs, or feature requests. Returns the created issue's identifier and URL. Required fields are title and teamId, with optional description, priority (0-4, where 0 is no priority and 1 is urgent), and status.", 527 | inputSchema: { 528 | type: "object", 529 | properties: { 530 | title: { type: "string", description: "Issue title" }, 531 | teamId: { type: "string", description: "Team ID" }, 532 | description: { type: "string", description: "Issue description" }, 533 | priority: { type: "number", description: "Priority (0-4)" }, 534 | status: { type: "string", description: "Issue status" } 535 | }, 536 | required: ["title", "teamId"] 537 | } 538 | }; 539 | 540 | const updateIssueTool: Tool = { 541 | name: "linear_update_issue", 542 | description: "Updates an existing Linear issue's properties. Use this to modify issue details like title, description, priority, or status. Requires the issue ID and accepts any combination of updatable fields. Returns the updated issue's identifier and URL.", 543 | inputSchema: { 544 | type: "object", 545 | properties: { 546 | id: { type: "string", description: "Issue ID" }, 547 | title: { type: "string", description: "New title" }, 548 | description: { type: "string", description: "New description" }, 549 | priority: { type: "number", description: "New priority (0-4)" }, 550 | status: { type: "string", description: "New status" } 551 | }, 552 | required: ["id"] 553 | } 554 | }; 555 | 556 | const searchIssuesTool: Tool = { 557 | name: "linear_search_issues", 558 | description: "Searches Linear issues using flexible criteria. Supports filtering by any combination of: title/description text, team, status, assignee, labels, priority (1=urgent, 2=high, 3=normal, 4=low), and estimate. Returns up to 10 issues by default (configurable via limit).", 559 | inputSchema: { 560 | type: "object", 561 | properties: { 562 | query: { type: "string", description: "Optional text to search in title and description" }, 563 | teamId: { type: "string", description: "Filter by team ID" }, 564 | status: { type: "string", description: "Filter by status name (e.g., 'In Progress', 'Done')" }, 565 | assigneeId: { type: "string", description: "Filter by assignee's user ID" }, 566 | labels: { 567 | type: "array", 568 | items: { type: "string" }, 569 | description: "Filter by label names" 570 | }, 571 | priority: { 572 | type: "number", 573 | description: "Filter by priority (1=urgent, 2=high, 3=normal, 4=low)" 574 | }, 575 | estimate: { 576 | type: "number", 577 | description: "Filter by estimate points" 578 | }, 579 | includeArchived: { 580 | type: "boolean", 581 | description: "Include archived issues in results (default: false)" 582 | }, 583 | limit: { 584 | type: "number", 585 | description: "Max results to return (default: 10)" 586 | } 587 | } 588 | } 589 | }; 590 | 591 | const getUserIssuesTool: Tool = { 592 | name: "linear_get_user_issues", 593 | description: "Retrieves issues assigned to a specific user or the authenticated user if no userId is provided. Returns issues sorted by last updated, including priority, status, and other metadata. Useful for finding a user's workload or tracking assigned tasks.", 594 | inputSchema: { 595 | type: "object", 596 | properties: { 597 | userId: { type: "string", description: "Optional user ID. If not provided, returns authenticated user's issues" }, 598 | includeArchived: { type: "boolean", description: "Include archived issues in results" }, 599 | limit: { type: "number", description: "Maximum number of issues to return (default: 50)" } 600 | } 601 | } 602 | }; 603 | 604 | const addCommentTool: Tool = { 605 | name: "linear_add_comment", 606 | description: "Adds a comment to an existing Linear issue. Supports markdown formatting in the comment body. Can optionally specify a custom user name and avatar for the comment. Returns the created comment's details including its URL.", 607 | inputSchema: { 608 | type: "object", 609 | properties: { 610 | issueId: { type: "string", description: "ID of the issue to comment on" }, 611 | body: { type: "string", description: "Comment text in markdown format" }, 612 | createAsUser: { type: "string", description: "Optional custom username to show for the comment" }, 613 | displayIconUrl: { type: "string", description: "Optional avatar URL for the comment" } 614 | }, 615 | required: ["issueId", "body"] 616 | } 617 | }; 618 | 619 | const resourceTemplates: ResourceTemplate[] = [ 620 | { 621 | uriTemplate: "linear-issue:///{issueId}", 622 | name: "Linear Issue", 623 | description: "A Linear issue with its details, comments, and metadata. Use this to fetch detailed information about a specific issue.", 624 | parameters: { 625 | issueId: { 626 | type: "string", 627 | description: "The unique identifier of the Linear issue (e.g., the internal ID)" 628 | } 629 | }, 630 | examples: [ 631 | "linear-issue:///c2b318fb-95d2-4a81-9539-f3268f34af87" 632 | ] 633 | }, 634 | { 635 | uriTemplate: "linear-viewer:", 636 | name: "Current User", 637 | description: "Information about the authenticated user associated with the API key, including their role, teams, and settings.", 638 | parameters: {}, 639 | examples: [ 640 | "linear-viewer:" 641 | ] 642 | }, 643 | { 644 | uriTemplate: "linear-organization:", 645 | name: "Current Organization", 646 | description: "Details about the Linear organization associated with the API key, including settings, teams, and members.", 647 | parameters: {}, 648 | examples: [ 649 | "linear-organization:" 650 | ] 651 | }, 652 | { 653 | uriTemplate: "linear-team:///{teamId}/issues", 654 | name: "Team Issues", 655 | description: "All active issues belonging to a specific Linear team, including their status, priority, and assignees.", 656 | parameters: { 657 | teamId: { 658 | type: "string", 659 | description: "The unique identifier of the Linear team (found in team settings)" 660 | } 661 | }, 662 | examples: [ 663 | "linear-team:///TEAM-123/issues" 664 | ] 665 | }, 666 | { 667 | uriTemplate: "linear-user:///{userId}/assigned", 668 | name: "User Assigned Issues", 669 | description: "Active issues assigned to a specific Linear user. Returns issues sorted by update date.", 670 | parameters: { 671 | userId: { 672 | type: "string", 673 | description: "The unique identifier of the Linear user. Use 'me' for the authenticated user" 674 | } 675 | }, 676 | examples: [ 677 | "linear-user:///USER-123/assigned", 678 | "linear-user:///me/assigned" 679 | ] 680 | } 681 | ]; 682 | 683 | const serverPrompt: Prompt = { 684 | name: "linear-server-prompt", 685 | description: "Instructions for using the Linear MCP server effectively", 686 | instructions: `This server provides access to Linear, a project management tool. Use it to manage issues, track work, and coordinate with teams. 687 | 688 | Key capabilities: 689 | - Create and update issues: Create new tickets or modify existing ones with titles, descriptions, priorities, and team assignments. 690 | - Search functionality: Find issues across the organization using flexible search queries with team and user filters. 691 | - Team coordination: Access team-specific issues and manage work distribution within teams. 692 | - Issue tracking: Add comments and track progress through status updates and assignments. 693 | - Organization overview: View team structures and user assignments across the organization. 694 | 695 | Tool Usage: 696 | - linear_create_issue: 697 | - use teamId from linear-organization: resource 698 | - priority levels: 1=urgent, 2=high, 3=normal, 4=low 699 | - status must match exact Linear workflow state names (e.g., "In Progress", "Done") 700 | 701 | - linear_update_issue: 702 | - get issue IDs from search_issues or linear-issue:/// resources 703 | - only include fields you want to change 704 | - status changes must use valid state IDs from the team's workflow 705 | 706 | - linear_search_issues: 707 | - combine multiple filters for precise results 708 | - use labels array for multiple tag filtering 709 | - query searches both title and description 710 | - returns max 10 results by default 711 | 712 | - linear_get_user_issues: 713 | - omit userId to get authenticated user's issues 714 | - useful for workload analysis and sprint planning 715 | - returns most recently updated issues first 716 | 717 | - linear_add_comment: 718 | - supports full markdown formatting 719 | - use displayIconUrl for bot/integration avatars 720 | - createAsUser for custom comment attribution 721 | 722 | Best practices: 723 | - When creating issues: 724 | - Write clear, actionable titles that describe the task well (e.g., "Implement user authentication for mobile app") 725 | - Include concise but appropriately detailed descriptions in markdown format with context and acceptance criteria 726 | - Set appropriate priority based on the context (1=critical to 4=nice-to-have) 727 | - Always specify the correct team ID (default to the user's team if possible) 728 | 729 | - When searching: 730 | - Use specific, targeted queries for better results (e.g., "auth mobile app" rather than just "auth") 731 | - Apply relevant filters when asked or when you can infer the appropriate filters to narrow results 732 | 733 | - When adding comments: 734 | - Use markdown formatting to improve readability and structure 735 | - Keep content focused on the specific issue and relevant updates 736 | - Include action items or next steps when appropriate 737 | 738 | - General best practices: 739 | - Fetch organization data first to get valid team IDs 740 | - Use search_issues to find issues for bulk operations 741 | - Include markdown formatting in descriptions and comments 742 | 743 | Resource patterns: 744 | - linear-issue:///{issueId} - Single issue details (e.g., linear-issue:///c2b318fb-95d2-4a81-9539-f3268f34af87) 745 | - linear-team:///{teamId}/issues - Team's issue list (e.g., linear-team:///OPS/issues) 746 | - linear-user:///{userId}/assigned - User assignments (e.g., linear-user:///USER-123/assigned) 747 | - linear-organization: - Organization for the current user 748 | - linear-viewer: - Current user context 749 | 750 | The server uses the authenticated user's permissions for all operations.` 751 | }; 752 | 753 | interface MCPMetricsResponse { 754 | apiMetrics: { 755 | requestsInLastHour: number; 756 | remainingRequests: number; 757 | averageRequestTime: string; 758 | queueLength: number; 759 | } 760 | } 761 | 762 | // Zod schemas for tool argument validation 763 | const CreateIssueArgsSchema = z.object({ 764 | title: z.string().describe("Issue title"), 765 | teamId: z.string().describe("Team ID"), 766 | description: z.string().optional().describe("Issue description"), 767 | priority: z.number().min(0).max(4).optional().describe("Priority (0-4)"), 768 | status: z.string().optional().describe("Issue status") 769 | }); 770 | 771 | const UpdateIssueArgsSchema = z.object({ 772 | id: z.string().describe("Issue ID"), 773 | title: z.string().optional().describe("New title"), 774 | description: z.string().optional().describe("New description"), 775 | priority: z.number().optional().describe("New priority (0-4)"), 776 | status: z.string().optional().describe("New status") 777 | }); 778 | 779 | const SearchIssuesArgsSchema = z.object({ 780 | query: z.string().optional().describe("Optional text to search in title and description"), 781 | teamId: z.string().optional().describe("Filter by team ID"), 782 | status: z.string().optional().describe("Filter by status name (e.g., 'In Progress', 'Done')"), 783 | assigneeId: z.string().optional().describe("Filter by assignee's user ID"), 784 | labels: z.array(z.string()).optional().describe("Filter by label names"), 785 | priority: z.number().optional().describe("Filter by priority (1=urgent, 2=high, 3=normal, 4=low)"), 786 | estimate: z.number().optional().describe("Filter by estimate points"), 787 | includeArchived: z.boolean().optional().describe("Include archived issues in results (default: false)"), 788 | limit: z.number().optional().describe("Max results to return (default: 10)") 789 | }); 790 | 791 | const GetUserIssuesArgsSchema = z.object({ 792 | userId: z.string().optional().describe("Optional user ID. If not provided, returns authenticated user's issues"), 793 | includeArchived: z.boolean().optional().describe("Include archived issues in results"), 794 | limit: z.number().optional().describe("Maximum number of issues to return (default: 50)") 795 | }); 796 | 797 | const AddCommentArgsSchema = z.object({ 798 | issueId: z.string().describe("ID of the issue to comment on"), 799 | body: z.string().describe("Comment text in markdown format"), 800 | createAsUser: z.string().optional().describe("Optional custom username to show for the comment"), 801 | displayIconUrl: z.string().optional().describe("Optional avatar URL for the comment") 802 | }); 803 | 804 | async function main() { 805 | try { 806 | dotenv.config(); 807 | 808 | const apiKey = process.env.LINEAR_API_KEY; 809 | if (!apiKey) { 810 | console.error("LINEAR_API_KEY environment variable is required"); 811 | process.exit(1); 812 | } 813 | 814 | console.error("Starting Linear MCP Server..."); 815 | const linearClient = new LinearMCPClient(apiKey); 816 | 817 | const server = new Server( 818 | { 819 | name: "linear-mcp-server", 820 | version: "1.0.0", 821 | }, 822 | { 823 | capabilities: { 824 | prompts: { 825 | default: serverPrompt 826 | }, 827 | resources: { 828 | templates: true, 829 | read: true 830 | }, 831 | tools: {}, 832 | }, 833 | } 834 | ); 835 | 836 | server.setRequestHandler(ListResourcesRequestSchema, async () => ({ 837 | resources: await linearClient.listIssues() 838 | })); 839 | 840 | server.setRequestHandler(ReadResourceRequestSchema, async (request) => { 841 | const uri = new URL(request.params.uri); 842 | const path = uri.pathname.replace(/^\//, ''); 843 | 844 | if (uri.protocol === 'linear-organization') { 845 | const organization = await linearClient.getOrganization(); 846 | return { 847 | contents: [{ 848 | uri: "linear-organization:", 849 | mimeType: "application/json", 850 | text: JSON.stringify(organization, null, 2) 851 | }] 852 | }; 853 | } 854 | 855 | if (uri.protocol === 'linear-viewer') { 856 | const viewer = await linearClient.getViewer(); 857 | return { 858 | contents: [{ 859 | uri: "linear-viewer:", 860 | mimeType: "application/json", 861 | text: JSON.stringify(viewer, null, 2) 862 | }] 863 | }; 864 | } 865 | 866 | if (uri.protocol === 'linear-issue:') { 867 | const issue = await linearClient.getIssue(path); 868 | return { 869 | contents: [{ 870 | uri: request.params.uri, 871 | mimeType: "application/json", 872 | text: JSON.stringify(issue, null, 2) 873 | }] 874 | }; 875 | } 876 | 877 | if (uri.protocol === 'linear-team:') { 878 | const [teamId] = path.split('/'); 879 | const issues = await linearClient.getTeamIssues(teamId); 880 | return { 881 | contents: [{ 882 | uri: request.params.uri, 883 | mimeType: "application/json", 884 | text: JSON.stringify(issues, null, 2) 885 | }] 886 | }; 887 | } 888 | 889 | if (uri.protocol === 'linear-user:') { 890 | const [userId] = path.split('/'); 891 | const issues = await linearClient.getUserIssues({ 892 | userId: userId === 'me' ? undefined : userId 893 | }); 894 | return { 895 | contents: [{ 896 | uri: request.params.uri, 897 | mimeType: "application/json", 898 | text: JSON.stringify(issues, null, 2) 899 | }] 900 | }; 901 | } 902 | 903 | throw new Error(`Unsupported resource URI: ${request.params.uri}`); 904 | }); 905 | 906 | server.setRequestHandler(ListToolsRequestSchema, async () => ({ 907 | tools: [createIssueTool, updateIssueTool, searchIssuesTool, getUserIssuesTool, addCommentTool] 908 | })); 909 | 910 | server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => { 911 | return { 912 | resourceTemplates: resourceTemplates 913 | }; 914 | }); 915 | 916 | server.setRequestHandler(ListPromptsRequestSchema, async () => { 917 | return { 918 | prompts: [serverPrompt] 919 | }; 920 | }); 921 | 922 | server.setRequestHandler(GetPromptRequestSchema, async (request) => { 923 | if (request.params.name === serverPrompt.name) { 924 | return { 925 | prompt: serverPrompt 926 | }; 927 | } 928 | throw new Error(`Prompt not found: ${request.params.name}`); 929 | }); 930 | 931 | server.setRequestHandler(CallToolRequestSchema, async (request: CallToolRequest) => { 932 | let metrics: RateLimiterMetrics = { 933 | totalRequests: 0, 934 | requestsInLastHour: 0, 935 | averageRequestTime: 0, 936 | queueLength: 0, 937 | lastRequestTime: Date.now() 938 | }; 939 | 940 | try { 941 | const { name, arguments: args } = request.params; 942 | if (!args) throw new Error("Missing arguments"); 943 | 944 | metrics = linearClient.rateLimiter.getMetrics(); 945 | 946 | const baseResponse: MCPMetricsResponse = { 947 | apiMetrics: { 948 | requestsInLastHour: metrics.requestsInLastHour, 949 | remainingRequests: linearClient.rateLimiter.requestsPerHour - metrics.requestsInLastHour, 950 | averageRequestTime: `${Math.round(metrics.averageRequestTime)}ms`, 951 | queueLength: metrics.queueLength 952 | } 953 | }; 954 | 955 | switch (name) { 956 | case "linear_create_issue": { 957 | const validatedArgs = CreateIssueArgsSchema.parse(args); 958 | const issue = await linearClient.createIssue(validatedArgs); 959 | return { 960 | content: [{ 961 | type: "text", 962 | text: `Created issue ${issue.identifier}: ${issue.title}\nURL: ${issue.url}`, 963 | metadata: baseResponse 964 | }] 965 | }; 966 | } 967 | 968 | case "linear_update_issue": { 969 | const validatedArgs = UpdateIssueArgsSchema.parse(args); 970 | const issue = await linearClient.updateIssue(validatedArgs); 971 | return { 972 | content: [{ 973 | type: "text", 974 | text: `Updated issue ${issue.identifier}\nURL: ${issue.url}`, 975 | metadata: baseResponse 976 | }] 977 | }; 978 | } 979 | 980 | case "linear_search_issues": { 981 | const validatedArgs = SearchIssuesArgsSchema.parse(args); 982 | const issues = await linearClient.searchIssues(validatedArgs); 983 | return { 984 | content: [{ 985 | type: "text", 986 | text: `Found ${issues.length} issues:\n${ 987 | issues.map((issue: LinearIssueResponse) => 988 | `- ${issue.identifier}: ${issue.title}\n Priority: ${issue.priority || 'None'}\n Status: ${issue.status || 'None'}\n ${issue.url}` 989 | ).join('\n') 990 | }`, 991 | metadata: baseResponse 992 | }] 993 | }; 994 | } 995 | 996 | case "linear_get_user_issues": { 997 | const validatedArgs = GetUserIssuesArgsSchema.parse(args); 998 | const issues = await linearClient.getUserIssues(validatedArgs); 999 | 1000 | return { 1001 | content: [{ 1002 | type: "text", 1003 | text: `Found ${issues.length} issues:\n${ 1004 | issues.map((issue: LinearIssueResponse) => 1005 | `- ${issue.identifier}: ${issue.title}\n Priority: ${issue.priority || 'None'}\n Status: ${issue.stateName}\n ${issue.url}` 1006 | ).join('\n') 1007 | }`, 1008 | metadata: baseResponse 1009 | }] 1010 | }; 1011 | } 1012 | 1013 | case "linear_add_comment": { 1014 | const validatedArgs = AddCommentArgsSchema.parse(args); 1015 | const { comment, issue } = await linearClient.addComment(validatedArgs); 1016 | 1017 | return { 1018 | content: [{ 1019 | type: "text", 1020 | text: `Added comment to issue ${issue?.identifier}\nURL: ${comment.url}`, 1021 | metadata: baseResponse 1022 | }] 1023 | }; 1024 | } 1025 | 1026 | default: 1027 | throw new Error(`Unknown tool: ${name}`); 1028 | } 1029 | } catch (error) { 1030 | console.error("Error executing tool:", error); 1031 | 1032 | const errorResponse: MCPMetricsResponse = { 1033 | apiMetrics: { 1034 | requestsInLastHour: metrics.requestsInLastHour, 1035 | remainingRequests: linearClient.rateLimiter.requestsPerHour - metrics.requestsInLastHour, 1036 | averageRequestTime: `${Math.round(metrics.averageRequestTime)}ms`, 1037 | queueLength: metrics.queueLength 1038 | } 1039 | }; 1040 | 1041 | // If it's a Zod error, format it nicely 1042 | if (error instanceof z.ZodError) { 1043 | const formattedErrors = error.errors.map(err => ({ 1044 | path: err.path, 1045 | message: err.message, 1046 | code: 'VALIDATION_ERROR' 1047 | })); 1048 | 1049 | return { 1050 | content: [{ 1051 | type: "text", 1052 | text: { 1053 | error: { 1054 | type: 'VALIDATION_ERROR', 1055 | message: 'Invalid request parameters', 1056 | details: formattedErrors 1057 | } 1058 | }, 1059 | metadata: { 1060 | error: true, 1061 | ...errorResponse 1062 | } 1063 | }] 1064 | }; 1065 | } 1066 | 1067 | // For Linear API errors, try to extract useful information 1068 | if (error instanceof Error && 'response' in error) { 1069 | return { 1070 | content: [{ 1071 | type: "text", 1072 | text: { 1073 | error: { 1074 | type: 'API_ERROR', 1075 | message: error.message, 1076 | details: { 1077 | // @ts-ignore - response property exists but isn't in type 1078 | status: error.response?.status, 1079 | // @ts-ignore - response property exists but isn't in type 1080 | data: error.response?.data 1081 | } 1082 | } 1083 | }, 1084 | metadata: { 1085 | error: true, 1086 | ...errorResponse 1087 | } 1088 | }] 1089 | }; 1090 | } 1091 | 1092 | // For all other errors 1093 | return { 1094 | content: [{ 1095 | type: "text", 1096 | text: { 1097 | error: { 1098 | type: 'UNKNOWN_ERROR', 1099 | message: error instanceof Error ? error.message : String(error) 1100 | } 1101 | }, 1102 | metadata: { 1103 | error: true, 1104 | ...errorResponse 1105 | } 1106 | }] 1107 | }; 1108 | } 1109 | }); 1110 | 1111 | const transport = new StdioServerTransport(); 1112 | console.error("Connecting server to transport..."); 1113 | await server.connect(transport); 1114 | console.error("Linear MCP Server running on stdio"); 1115 | } catch (error) { 1116 | console.error(`Fatal error in main(): ${error instanceof Error ? error.message : String(error)}`); 1117 | process.exit(1); 1118 | } 1119 | } 1120 | 1121 | main().catch((error: unknown) => { 1122 | console.error("Fatal error in main():", error instanceof Error ? error.message : String(error)); 1123 | process.exit(1); 1124 | }); 1125 | -------------------------------------------------------------------------------- /package-lock.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "linear-mcp-server", 3 | "version": "0.1.0", 4 | "lockfileVersion": 3, 5 | "requires": true, 6 | "packages": { 7 | "": { 8 | "name": "linear-mcp-server", 9 | "version": "0.1.0", 10 | "dependencies": { 11 | "@linear/sdk": "^33.0.0", 12 | "@modelcontextprotocol/sdk": "^1.0.3", 13 | "dotenv": "^16.4.6", 14 | "zod": "^3.24.2" 15 | }, 16 | "bin": { 17 | "linear-mcp-server": "build/index.js" 18 | }, 19 | "devDependencies": { 20 | "@types/node": "^20.17.9", 21 | "typescript": "^5.3.3" 22 | } 23 | }, 24 | "node_modules/@graphql-typed-document-node/core": { 25 | "version": "3.2.0", 26 | "resolved": "https://registry.npmjs.org/@graphql-typed-document-node/core/-/core-3.2.0.tgz", 27 | "integrity": "sha512-mB9oAsNCm9aM3/SOv4YtBMqZbYj10R7dkq8byBqxGY/ncFwhf2oQzMV+LCRlWoDSEBJ3COiR1yeDvMtsoOsuFQ==", 28 | "peerDependencies": { 29 | "graphql": "^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0 || ^14.0.0 || ^15.0.0 || ^16.0.0 || ^17.0.0" 30 | } 31 | }, 32 | "node_modules/@linear/sdk": { 33 | "version": "33.0.0", 34 | "resolved": "https://registry.npmjs.org/@linear/sdk/-/sdk-33.0.0.tgz", 35 | "integrity": "sha512-T+ZW9PTgVSp00I/2tCgan1LGHa1TrlSU8EuJleIcKldFYsltekSc9duSUaDB28b48zDbHlOCSKzISDpO4dSQ/g==", 36 | "dependencies": { 37 | "@graphql-typed-document-node/core": "^3.1.0", 38 | "graphql": "^15.4.0", 39 | "isomorphic-unfetch": "^3.1.0" 40 | }, 41 | "engines": { 42 | "node": ">=12.x", 43 | "yarn": "1.x" 44 | } 45 | }, 46 | "node_modules/@modelcontextprotocol/sdk": { 47 | "version": "1.0.3", 48 | "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.0.3.tgz", 49 | "integrity": "sha512-2as3cX/VJ0YBHGmdv3GFyTpoM8q2gqE98zh3Vf1NwnsSY0h3mvoO07MUzfygCKkWsFjcZm4otIiqD6Xh7kiSBQ==", 50 | "dependencies": { 51 | "content-type": "^1.0.5", 52 | "raw-body": "^3.0.0", 53 | "zod": "^3.23.8" 54 | } 55 | }, 56 | "node_modules/@types/node": { 57 | "version": "20.17.9", 58 | "resolved": "https://registry.npmjs.org/@types/node/-/node-20.17.9.tgz", 59 | "integrity": "sha512-0JOXkRyLanfGPE2QRCwgxhzlBAvaRdCNMcvbd7jFfpmD4eEXll7LRwy5ymJmyeZqk7Nh7eD2LeUyQ68BbndmXw==", 60 | "dev": true, 61 | "dependencies": { 62 | "undici-types": "~6.19.2" 63 | } 64 | }, 65 | "node_modules/bytes": { 66 | "version": "3.1.2", 67 | "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", 68 | "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==", 69 | "engines": { 70 | "node": ">= 0.8" 71 | } 72 | }, 73 | "node_modules/content-type": { 74 | "version": "1.0.5", 75 | "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz", 76 | "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==", 77 | "engines": { 78 | "node": ">= 0.6" 79 | } 80 | }, 81 | "node_modules/depd": { 82 | "version": "2.0.0", 83 | "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", 84 | "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==", 85 | "engines": { 86 | "node": ">= 0.8" 87 | } 88 | }, 89 | "node_modules/dotenv": { 90 | "version": "16.4.6", 91 | "resolved": "https://registry.npmjs.org/dotenv/-/dotenv-16.4.6.tgz", 92 | "integrity": "sha512-JhcR/+KIjkkjiU8yEpaB/USlzVi3i5whwOjpIRNGi9svKEXZSe+Qp6IWAjFjv+2GViAoDRCUv/QLNziQxsLqDg==", 93 | "engines": { 94 | "node": ">=12" 95 | }, 96 | "funding": { 97 | "url": "https://dotenvx.com" 98 | } 99 | }, 100 | "node_modules/graphql": { 101 | "version": "15.9.0", 102 | "resolved": "https://registry.npmjs.org/graphql/-/graphql-15.9.0.tgz", 103 | "integrity": "sha512-GCOQdvm7XxV1S4U4CGrsdlEN37245eC8P9zaYCMr6K1BG0IPGy5lUwmJsEOGyl1GD6HXjOtl2keCP9asRBwNvA==", 104 | "engines": { 105 | "node": ">= 10.x" 106 | } 107 | }, 108 | "node_modules/http-errors": { 109 | "version": "2.0.0", 110 | "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.0.tgz", 111 | "integrity": "sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ==", 112 | "dependencies": { 113 | "depd": "2.0.0", 114 | "inherits": "2.0.4", 115 | "setprototypeof": "1.2.0", 116 | "statuses": "2.0.1", 117 | "toidentifier": "1.0.1" 118 | }, 119 | "engines": { 120 | "node": ">= 0.8" 121 | } 122 | }, 123 | "node_modules/iconv-lite": { 124 | "version": "0.6.3", 125 | "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz", 126 | "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==", 127 | "dependencies": { 128 | "safer-buffer": ">= 2.1.2 < 3.0.0" 129 | }, 130 | "engines": { 131 | "node": ">=0.10.0" 132 | } 133 | }, 134 | "node_modules/inherits": { 135 | "version": "2.0.4", 136 | "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", 137 | "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==" 138 | }, 139 | "node_modules/isomorphic-unfetch": { 140 | "version": "3.1.0", 141 | "resolved": "https://registry.npmjs.org/isomorphic-unfetch/-/isomorphic-unfetch-3.1.0.tgz", 142 | "integrity": "sha512-geDJjpoZ8N0kWexiwkX8F9NkTsXhetLPVbZFQ+JTW239QNOwvB0gniuR1Wc6f0AMTn7/mFGyXvHTifrCp/GH8Q==", 143 | "dependencies": { 144 | "node-fetch": "^2.6.1", 145 | "unfetch": "^4.2.0" 146 | } 147 | }, 148 | "node_modules/node-fetch": { 149 | "version": "2.7.0", 150 | "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz", 151 | "integrity": "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==", 152 | "dependencies": { 153 | "whatwg-url": "^5.0.0" 154 | }, 155 | "engines": { 156 | "node": "4.x || >=6.0.0" 157 | }, 158 | "peerDependencies": { 159 | "encoding": "^0.1.0" 160 | }, 161 | "peerDependenciesMeta": { 162 | "encoding": { 163 | "optional": true 164 | } 165 | } 166 | }, 167 | "node_modules/raw-body": { 168 | "version": "3.0.0", 169 | "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.0.tgz", 170 | "integrity": "sha512-RmkhL8CAyCRPXCE28MMH0z2PNWQBNk2Q09ZdxM9IOOXwxwZbN+qbWaatPkdkWIKL2ZVDImrN/pK5HTRz2PcS4g==", 171 | "dependencies": { 172 | "bytes": "3.1.2", 173 | "http-errors": "2.0.0", 174 | "iconv-lite": "0.6.3", 175 | "unpipe": "1.0.0" 176 | }, 177 | "engines": { 178 | "node": ">= 0.8" 179 | } 180 | }, 181 | "node_modules/safer-buffer": { 182 | "version": "2.1.2", 183 | "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", 184 | "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==" 185 | }, 186 | "node_modules/setprototypeof": { 187 | "version": "1.2.0", 188 | "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", 189 | "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==" 190 | }, 191 | "node_modules/statuses": { 192 | "version": "2.0.1", 193 | "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.1.tgz", 194 | "integrity": "sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==", 195 | "engines": { 196 | "node": ">= 0.8" 197 | } 198 | }, 199 | "node_modules/toidentifier": { 200 | "version": "1.0.1", 201 | "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz", 202 | "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==", 203 | "engines": { 204 | "node": ">=0.6" 205 | } 206 | }, 207 | "node_modules/tr46": { 208 | "version": "0.0.3", 209 | "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", 210 | "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==" 211 | }, 212 | "node_modules/typescript": { 213 | "version": "5.7.2", 214 | "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.7.2.tgz", 215 | "integrity": "sha512-i5t66RHxDvVN40HfDd1PsEThGNnlMCMT3jMUuoh9/0TaqWevNontacunWyN02LA9/fIbEWlcHZcgTKb9QoaLfg==", 216 | "dev": true, 217 | "bin": { 218 | "tsc": "bin/tsc", 219 | "tsserver": "bin/tsserver" 220 | }, 221 | "engines": { 222 | "node": ">=14.17" 223 | } 224 | }, 225 | "node_modules/undici-types": { 226 | "version": "6.19.8", 227 | "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.19.8.tgz", 228 | "integrity": "sha512-ve2KP6f/JnbPBFyobGHuerC9g1FYGn/F8n1LWTwNxCEzd6IfqTwUQcNXgEtmmQ6DlRrC1hrSrBnCZPokRrDHjw==", 229 | "dev": true 230 | }, 231 | "node_modules/unfetch": { 232 | "version": "4.2.0", 233 | "resolved": "https://registry.npmjs.org/unfetch/-/unfetch-4.2.0.tgz", 234 | "integrity": "sha512-F9p7yYCn6cIW9El1zi0HI6vqpeIvBsr3dSuRO6Xuppb1u5rXpCPmMvLSyECLhybr9isec8Ohl0hPekMVrEinDA==" 235 | }, 236 | "node_modules/unpipe": { 237 | "version": "1.0.0", 238 | "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz", 239 | "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==", 240 | "engines": { 241 | "node": ">= 0.8" 242 | } 243 | }, 244 | "node_modules/webidl-conversions": { 245 | "version": "3.0.1", 246 | "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", 247 | "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==" 248 | }, 249 | "node_modules/whatwg-url": { 250 | "version": "5.0.0", 251 | "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", 252 | "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", 253 | "dependencies": { 254 | "tr46": "~0.0.3", 255 | "webidl-conversions": "^3.0.0" 256 | } 257 | }, 258 | "node_modules/zod": { 259 | "version": "3.24.2", 260 | "resolved": "https://registry.npmjs.org/zod/-/zod-3.24.2.tgz", 261 | "integrity": "sha512-lY7CDW43ECgW9u1TcT3IoXHflywfVqDYze4waEz812jR/bZ8FHDsl7pFQoSZTz5N+2NqRXs8GBwnAwo3ZNxqhQ==", 262 | "license": "MIT", 263 | "funding": { 264 | "url": "https://github.com/sponsors/colinhacks" 265 | } 266 | } 267 | } 268 | } 269 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "linear-mcp-server", 3 | "version": "0.1.0", 4 | "description": "A Model Context Protocol server for the Linear API.", 5 | "type": "module", 6 | "bin": { 7 | "linear-mcp-server": "build/index.js" 8 | }, 9 | "files": [ 10 | "build" 11 | ], 12 | "scripts": { 13 | "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"", 14 | "prepare": "npm run build", 15 | "watch": "tsc --watch", 16 | "inspector": "npx @modelcontextprotocol/inspector build/index.js" 17 | }, 18 | "dependencies": { 19 | "@linear/sdk": "^33.0.0", 20 | "@modelcontextprotocol/sdk": "^1.0.3", 21 | "dotenv": "^16.4.6", 22 | "zod": "^3.24.2" 23 | }, 24 | "devDependencies": { 25 | "@types/node": "^20.17.9", 26 | "typescript": "^5.3.3" 27 | }, 28 | "repository": { 29 | "type": "git", 30 | "url": "https://github.com/modelcontextprotocol/linear-server.git" 31 | }, 32 | "keywords": [ 33 | "linear", 34 | "mcp", 35 | "model context protocol", 36 | "api", 37 | "server" 38 | ], 39 | "author": "Model Context Protocol", 40 | "license": "MIT" 41 | } 42 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "ES2022", 4 | "module": "Node16", 5 | "moduleResolution": "Node16", 6 | "esModuleInterop": true, 7 | "outDir": "./build", 8 | "rootDir": ".", 9 | "strict": true, 10 | "skipLibCheck": true, 11 | "forceConsistentCasingInFileNames": true, 12 | "types": ["node"] 13 | }, 14 | "include": ["index.ts"], 15 | "exclude": ["node_modules", "build"] 16 | } 17 | --------------------------------------------------------------------------------