Linear MCP Server
A Model Context Protocol (MCP) server implementation that provides access to Linear's issue tracking system through a standardized interface.
Features
- Create new issues and subissues with label support
- Retrieve the list of linear projects
- Retrieve the project updates
- Create a new project update with health status
- Update existing issues with full field modification
- Delete issue with validation
- Self-assign issues using 'me' keyword
- Advanced search with Linear's powerful filtering capabilities
- Filter issues by cycle (current, next, previous, or specific cycle by UUID or number)
- Add comments to issues with markdown support
- Query Linear issues by ID or key with optional relationships
- Search issues using custom queries with enhanced metadata
- Type-safe operations using Linear's official SDK
- Comprehensive error handling
- Rate limit handling
- Clean data transformation
- Parent/child relationship tracking with team inheritance
- Label management and synchronization
Prerequisites
- Bun runtime (v1.0.0 or higher)
- Linear account with API access
Environment Variables
Installation & Setup
1. Clone the repository:
2. Install dependencies and build:
3. Configure the MCP server:
Edit the appropriate configuration file:
macOS:
- Cline:
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
- Cline:
%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
- Claude Desktop:
%APPDATA%\Claude Desktop\claude_desktop_config.json
Linux:
- Cline:
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Claude Desktop: sadly doesn't exist yet
Add the following configuration under the
mcpServers object:4. Restart the MCP server.
Within Cline's MCP settings, restart the MCP server. Restart Claude Desktop to load the new MCP server.
Development
Run development server:
Build project:
Available MCP Tools
For detailed usage examples of all tools, see USAGE.md.
create_issue
Create a new Linear issue or subissue.
Input Schema:
update_issue
Update an existing Linear issue.
Input Schema:
get_issue
Get detailed information about a specific Linear issue with optional relationships.
Input Schema:
search_issues
Search for Linear issues using a query string and advanced filters. Supports Linear's powerful filtering capabilities.
Input Schema:
Supported Comparators:
- String fields:
eq,neq,in,nin,contains,startsWith,endsWith(plus case-insensitive variants)
- Number fields:
eq,neq,lt,lte,gt,gte,in,nin
- Date fields:
eq,neq,lt,lte,gt,gte(supports ISO 8601 durations)
get_teams
Get a list of Linear teams with optional name/key filtering.
Input Schema:
delete_issue
Delete an existing Linear issue.
Input Schema:
create_comment
Create a new comment on a Linear issue.
Input Schema:
get_projects
Get a list of Linear projects with optional name filtering and pagination.
Input Schema:
get_project_updates
Get project updates for a given project ID with optional filtering parameters.
Input Schema:
create_project_update
Create a new update for a Linear project.
Input Schema:
Technical Details
- Built with TypeScript in strict mode
- Uses Linear's official SDK (@linear/sdk)
- Uses MCP SDK (@modelcontextprotocol/sdk 1.4.0)
- Authentication via API tokens
- Comprehensive error handling
- Rate limiting considerations
- Bun runtime for improved performance
- ESM modules throughout
- Vite build system
- Type-safe operations
- Data cleaning features:
- Self-assignment support:
- Advanced search capabilities:
- Project management features:
Error Handling
The server implements a comprehensive error handling strategy:
- Network error detection and appropriate messaging
- HTTP status code handling
- Detailed error messages with status codes
- Error details logging to console
- Input validation for all parameters
- Label validation and synchronization
- Safe error propagation through MCP protocol
- Rate limit detection and handling
- Authentication error handling
- Invalid query handling
- Team inheritance validation for subissues
- User resolution validation
- Search filter validation
LICENCE
This project is licensed under the MIT License - see the LICENCE file for details.
Linear MCP Server
A Model Context Protocol (MCP) server implementation that provides access to Linear's issue tracking system through a standardized interface.
Features
- Create new issues and subissues with label support
- Retrieve the list of linear projects
- Retrieve the project updates
- Create a new project update with health status
- Update existing issues with full field modification
- Delete issue with validation
- Self-assign issues using 'me' keyword
- Advanced search with Linear's powerful filtering capabilities
- Filter issues by cycle (current, next, previous, or specific cycle by UUID or number)
- Add comments to issues with markdown support
- Query Linear issues by ID or key with optional relationships
- Search issues using custom queries with enhanced metadata
- Type-safe operations using Linear's official SDK
- Comprehensive error handling
- Rate limit handling
- Clean data transformation
- Parent/child relationship tracking with team inheritance
- Label management and synchronization
Prerequisites
- Bun runtime (v1.0.0 or higher)
- Linear account with API access
Environment Variables
Installation & Setup
1. Clone the repository:
2. Install dependencies and build:
3. Configure the MCP server:
Edit the appropriate configuration file:
macOS:
- Cline:
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
- Cline:
%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
- Claude Desktop:
%APPDATA%\Claude Desktop\claude_desktop_config.json
Linux:
- Cline:
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Claude Desktop: sadly doesn't exist yet
Add the following configuration under the
mcpServers object:4. Restart the MCP server.
Within Cline's MCP settings, restart the MCP server. Restart Claude Desktop to load the new MCP server.
Development
Run development server:
Build project:
Available MCP Tools
For detailed usage examples of all tools, see USAGE.md.
create_issue
Create a new Linear issue or subissue.
Input Schema:
update_issue
Update an existing Linear issue.
Input Schema:
get_issue
Get detailed information about a specific Linear issue with optional relationships.
Input Schema:
search_issues
Search for Linear issues using a query string and advanced filters. Supports Linear's powerful filtering capabilities.
Input Schema:
Supported Comparators:
- String fields:
eq,neq,in,nin,contains,startsWith,endsWith(plus case-insensitive variants)
- Number fields:
eq,neq,lt,lte,gt,gte,in,nin
- Date fields:
eq,neq,lt,lte,gt,gte(supports ISO 8601 durations)
get_teams
Get a list of Linear teams with optional name/key filtering.
Input Schema:
delete_issue
Delete an existing Linear issue.
Input Schema:
create_comment
Create a new comment on a Linear issue.
Input Schema:
get_projects
Get a list of Linear projects with optional name filtering and pagination.
Input Schema:
get_project_updates
Get project updates for a given project ID with optional filtering parameters.
Input Schema:
create_project_update
Create a new update for a Linear project.
Input Schema:
Technical Details
- Built with TypeScript in strict mode
- Uses Linear's official SDK (@linear/sdk)
- Uses MCP SDK (@modelcontextprotocol/sdk 1.4.0)
- Authentication via API tokens
- Comprehensive error handling
- Rate limiting considerations
- Bun runtime for improved performance
- ESM modules throughout
- Vite build system
- Type-safe operations
- Data cleaning features:
- Self-assignment support:
- Advanced search capabilities:
- Project management features:
Error Handling
The server implements a comprehensive error handling strategy:
- Network error detection and appropriate messaging
- HTTP status code handling
- Detailed error messages with status codes
- Error details logging to console
- Input validation for all parameters
- Label validation and synchronization
- Safe error propagation through MCP protocol
- Rate limit detection and handling
- Authentication error handling
- Invalid query handling
- Team inheritance validation for subissues
- User resolution validation
- Search filter validation
LICENCE
This project is licensed under the MIT License - see the LICENCE file for details.