-
securityF
license-
qualityEnables AI models to interact with Linear for issue tracking and project management through capabilities like creating/searching issues, managing sprints, and retrieving workflow states.
Last updated -
The Linear MCP Server enables AI models to interact with Linear issue tracking via the MCP protocol. With this server, you can:
Search and manage issues/tickets: List with filtering options, retrieve details, create new issues, and add comments
Access team information: List teams, members, and filter by various criteria
Work with projects: List projects with filtering, get detailed project information including associated issues and team members
Customize operations: Set priorities, assignees, descriptions, and other attributes when creating or managing items
Integrate with AI applications: Works with MCP Inspector, Claude Desktop, Cursor, and supports debugging functionality
Provides tools for searching, reading, updating, and commenting on issues in Linear's issue tracking system.
Linear MCP Server
A Node.js implementation of an MCP server for Linear integration.
About
This MCP (Model Context Protocol) server provides a standardized interface for AI models to interact with Linear issue tracking functionality.
Key Features
Standard MCP protocol implementation for Linear using the official MCP SDK
Support for searching issues, reading details, updating, and commenting
Getting Started
Prerequisites
Node.js (v18 or later)
Linear API key
Installation
Clone the repository
Install dependencies
npm install
Create a
.envfile in the root directory with your Linear API key
LINEAR_API_KEY=your_linear_api_key_here
Running the Server
Start the server:
npm start
For development with file watching:
just dev
For development with debug logging:
just debug
Or set environment variables manually:
LOG_LEVEL=DEBUG NODE_ENV=development node src/index.js
Logs will be written to the logs/mcp-linear.log file to avoid interfering with the STDIO transport.
Using with MCP Inspector
The server runs in stdio mode, which means you can connect to it with the MCP Inspector.
Start the server in one terminal:
npm start
Visit the web-based inspector at: https://inspector.modelcontextprotocol.ai
Select "stdio" as the transport type
Enter the following command:
node /path/to/mcp-linear/src/index.js
Click "Connect" to connect to your running server
Usage with Claude Desktop
Add the following to your Claude Desktop configuration file (typically at
~/.config/Claude Desktop/claude_desktop_config.json):
{
"mcp": {
"servers": [
{
"name": "Linear",
"command": "node /path/to/mcp-linear/src/index.js",
"env": {
"LINEAR_API_KEY": "your_linear_api_key_here"
}
}
]
}
}
Usage with Cursor
For Cursor, add the following to your settings:
{
"ai.mcp.servers": [
{
"name": "Linear",
"command": "node /path/to/mcp-linear/src/index.js",
"env": {
"LINEAR_API_KEY": "your_linear_api_key_here"
}
}
]
}
Testing Your Integration
To verify your setup:
Configure the MCP server in your Claude Desktop or Cursor settings
Restart your application
Ask: "Search for Linear issues containing 'bug'"
The assistant should detect and use the Linear MCP server to retrieve results
Project Structure
/
├── src/ # Source code
│ ├── effects/ # Effects implementation
│ │ ├── linear/ # Linear API effects
│ │ │ └── types/ # Linear type definitions
│ │ └── logging/ # Logging effects for safe logging with STDIO
│ ├── tools/ # MCP tools implementation
│ │ ├── types/ # Tool type definitions
│ │ └── utils/ # Tool utility functions
│ ├── utils/ # Utility modules
│ │ └── config/ # Configuration utilities
│ └── index.js # Main entry point
├── docs/ # Documentation
│ └── llm_context/ # Documentation for LLMs
├── logs/ # Log files (created at runtime)
└── package.json # Project configuration
Available Tools
The MCP server exposes the following tools:
list_issues- List Linear issues (also called tickets) with various filtering options (assignee, status, etc.)get_issue- Get detailed information about a specific Linear issue by IDlist_members- List Linear team members with optional filtering by namelist_projects- List Linear projects with optional filtering by team, name, and archive statusget_project- Get detailed information about a specific Linear project including issues, members and morelist_teams- List Linear teams with details about their members, projects, and issuesadd_comment- Add a comment to a specific Linear issuecreate_issue- Create a new issue in Linear with customizable title, description, priority, and assignee
For backward compatibility, the following tool aliases are also available:
list_tickets- Alias forlist_issuesget_ticket- Alias forget_issue
Troubleshooting
If you're having issues with the Linear MCP server:
Check your Linear API key: Make sure you've set a valid Linear API key in your .env file or environment variables. Linear API keys should start with "linapi".
Enable debug logging:
a. When starting the MCP server:
just debug # or LOG_LEVEL=DEBUG NODE_ENV=development node src/index.jsb. In your client configuration (Claude Desktop, Cursor, etc.):
"env": { "LINEAR_API_KEY": "your_linear_api_key_here", "LOG_LEVEL": "DEBUG" }c. When calling tools directly, add the debug parameter:
{ "debug": true }Check log files: Examine logs in the
logs/mcp-linear.logfile for detailed error information.Verify Linear API access: Make sure your Linear API key has appropriate permissions and that you can access the Linear API directly.
Architecture
The application follows an effects-based architecture:
Effects: Side-effecting operations are isolated in the
effectsdirectory:linear: Provides access to Linear API using the official Linear SDKlogging: Safe logging that doesn't interfere with STDIO transport
Tools: MCP tool implementations that use effects for side-effects:
Each tool follows a consistent pattern with input validation using Zod
Tools are exposed through the MCP protocol via the server
Each tool can access the Linear client through the linear effect
Utils: Utility modules for configuration and common functionality
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Deno implementation that enables AI models to interact with Linear issue tracking functionality, supporting searching issues, reading details, updating, and commenting.
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that integrates with Linear, enabling AI assistants to create, update, search, and comment on issues for project management and issue tracking.Last updated -6Apache 2.0
- -securityFlicense-qualityAllows LLMs to integrate with Linear's issue tracking system, enabling them to create, update, search, and comment on issues through the Linear API.Last updated -236
- -securityAlicense-qualityProvides access to Linear's issue tracking system through a standardized Model Context Protocol interface, allowing users to create, update, search, and manage issues, projects, and comments via natural language.Last updated -1,4541MIT License