README.md•6.24 kB
# 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](https://nodejs.org/) (v18 or later)
- Linear API key
### Installation
1. Clone the repository
2. Install dependencies
```bash
npm install
```
3. Create a `.env` file in the root directory with your Linear API key
```
LINEAR_API_KEY=your_linear_api_key_here
```
### Running the Server
Start the server:
```bash
npm start
```
For development with file watching:
```bash
just dev
```
For development with debug logging:
```bash
just debug
```
Or set environment variables manually:
```bash
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.
1. Start the server in one terminal:
```bash
npm start
```
2. Visit the web-based inspector at: https://inspector.modelcontextprotocol.ai
3. Select "stdio" as the transport type
4. Enter the following command:
```
node /path/to/mcp-linear/src/index.js
```
5. 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`):
```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:
```json
{
"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:
1. Configure the MCP server in your Claude Desktop or Cursor settings
2. Restart your application
3. Ask: "Search for Linear issues containing 'bug'"
4. 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 ID
- `list_members` - List Linear team members with optional filtering by name
- `list_projects` - List Linear projects with optional filtering by team, name, and archive status
- `get_project` - Get detailed information about a specific Linear project including issues, members and more
- `list_teams` - List Linear teams with details about their members, projects, and issues
- `add_comment` - Add a comment to a specific Linear issue
- `create_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 for `list_issues`
- `get_ticket` - Alias for `get_issue`
## Troubleshooting
If you're having issues with the Linear MCP server:
1. **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 "lin*api*".
2. **Enable debug logging**:
a. When starting the MCP server:
```bash
just debug
# or
LOG_LEVEL=DEBUG NODE_ENV=development node src/index.js
```
b. In your client configuration (Claude Desktop, Cursor, etc.):
```json
"env": {
"LINEAR_API_KEY": "your_linear_api_key_here",
"LOG_LEVEL": "DEBUG"
}
```
c. When calling tools directly, add the debug parameter:
```json
{
"debug": true
}
```
3. **Check log files**: Examine logs in the `logs/mcp-linear.log` file for detailed error information.
4. **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 `effects` directory:
- `linear`: Provides access to Linear API using the official Linear SDK
- `logging`: 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.