mcp-linear

The Linear MCP Integration Server exposes a set of MCP tools that bridge AI models with Linear’s issue tracking and project management capabilities. Through the MCP interface, you can create and search issues, manage sprints, retrieve detailed issue data, and bulk-update issue statuses. Key tools include linear_create_issue for creating new Linear issues, linear_search_issues for flexible, paginated queries, linear_sprint_issues to list issues in the current sprint, linear_get_issue_details to fetch comprehensive issue metadata, and linear_bulk_update_status to apply a target status to multiple issues at once. There are also utilities like linear_filter_sprint_issues to narrow sprint results by status and user, linear_search_teams to discover teams, and linear_manage_cycle to create, update, or fetch sprint-like cycles. These tools leverage the Linear API via the MCP framework, handling authentication, retries, and error handling, while offering pagination, caching, and robust logging for diagnostics.

Prerequisites:

• Node.js (recommended LTS) and npm installed on your machine
• Access to a Linear API key

Installation steps:

1. Clone the repository: git clone https://github.com/your-org/mcp-linear.git cd mcp-linear

2. Install dependencies: npm install

3. Configure environment:

   • Create a .env file in the project root with your Linear API key: LINEAR_API_KEY=your_api_key_here

4. Build the project (TypeScript): npm run build

5. Run in development mode (with auto-reload if configured): npm run dev

6. Start in production mode: npm start

7. (Optional) Validate MCP setup with inspector: npm run inspect

Notes:

• Ensure your Linear API key has the required scopes for the operations you intend to perform.
• If you deploy via Smithery, follow the Smithery deployment workflow and provide LINEAR_API_KEY as an environment variable in the deployment settings.

Tips and known considerations:

• The server caches frequently requested data (e.g., teams and workflow states) to improve performance; you can adjust TTL settings via environment variables if exposed by the deployment.
• Monitor rate limits from the Linear API; the MCP layer includes retry logic and backoff configurations.
• For debugging, enable debug logging to capture MCP interactions and HTTP requests to Linear.
• Ensure your environment securely stores API keys; avoid committing them to source control.
• When using bulk operations (linear_bulk_update_status), verify the list of issue IDs to prevent unintended updates.
• If integrating with Smithery, provide the LINEAR_API_KEY in the smithery.yaml or via the deployment configuration; the Dockerfile and smithery.yaml describe how environment variables are wired.