Content
# mcp-server-linear
Model Context Protocol (MCP) server for interacting with the Linear API. This server provides tools and resources for accessing and manipulating Linear issues, projects, and other data through a standardized MCP interface.
## Overview
The `mcp-server-linear` project serves as a bridge between client applications (particularly AI assistants and other tools) and Linear, providing a standardized interface for accessing and manipulating Linear resources.
Key features:
- Standardized access to Linear resources (issues, projects, initiatives, teams)
- Full CRUD operations for issues and comments
- Advanced issue filtering and search capabilities
- Consistent error handling and response formats
- Integration with AI assistants through MCP protocol
## Configuration
### Linear API Authentication
This server supports two authentication methods:
#### Option 1: API Key Authentication
You can set up the `LINEAR_API_KEY` environment variable:
1. Go to [Linear Settings > API](https://linear.app/settings/api)
2. Under "Personal API keys", click "Create key"
3. Give your key a name (e.g., "MCP Server")
4. Copy the generated API key
5. Set the environment variable when running the server
#### Option 2: OAuth Authentication
Alternatively, you can use OAuth authentication by setting the following environment variables:
1. Create an OAuth application at [Linear Settings > API > Applications](https://linear.app/settings/api/applications)
2. Configure your application and obtain the client ID and client secret
3. Set the following environment variables:
```bash
LINEAR_OAUTH_CLIENT_ID=your_oauth_client_id
LINEAR_OAUTH_CLIENT_SECRET=your_oauth_client_secret
```
If both authentication methods are configured, OAuth authentication will be prioritized.
Alternatively, you can set the environment variables in your shell profile or use a tool like `dotenv`.
## Usage
### Starting the Server
You can run the MCP server directly using npx without installing it globally:
```bash
LINEAR_API_KEY=your_api_key_here npx -y @mkusaka/mcp-server-linear
```
### Integration with MCP Clients
This MCP server can be integrated with various AI assistants and MCP-compatible clients:
#### Anthropic Claude Integration
You can use this MCP server with Anthropic Claude through various clients:
##### Cline (VS Code Extension)
[Cline](https://github.com/saoudrizwan/cline) is a VS Code extension that allows you to use MCP servers with Claude AI:
1. Open your Cline MCP settings file:
- macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- Windows: `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- Linux: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
2. Add the Linear MCP server configuration:
```json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@mkusaka/mcp-server-linear"],
"env": {
"LINEAR_API_KEY": "your_linear_api_key"
// or when using OAuth authentication
// "LINEAR_OAUTH_CLIENT_ID": "your_oauth_client_id",
// "LINEAR_OAUTH_CLIENT_SECRET": "your_oauth_client_secret"
},
"disabled": false,
"autoApprove": []
}
}
}
```
##### Cursor
Add the following to your Cursor configuration file (`~/.cursor/config.json`):
```json
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "@mkusaka/mcp-server-linear"],
"env": {
"LINEAR_API_KEY": "your_linear_api_key"
// or when using OAuth authentication
// "LINEAR_OAUTH_CLIENT_ID": "your_oauth_client_id",
// "LINEAR_OAUTH_CLIENT_SECRET": "your_oauth_client_secret"
},
"disabled": false,
"autoApprove": []
}
}
}
```
### Available Tools
This MCP server provides the following tools:
#### Issue Management
- `create_issue` - Create a new issue in Linear
- `update_issue` - Update an existing issue
- `delete_issue` - Delete an existing issue
- `update_issue_labels` - Update the labels of an issue
- `update_issue_priority` - Update the priority of an issue
- `update_issue_estimate` - Update the estimate of an issue
- `update_issue_state` - Update the state of an issue
- `search_issues` - Search for issues with advanced filtering options
#### Comment Management
- `create_comment` - Create a new comment on an issue
- `update_comment` - Update an existing comment
- `delete_comment` - Delete an existing comment
- `get_issue_comments` - Get comments for a specific issue
#### Resource Access
- `projects` - Get all projects in Linear
- `project` - Get a single project by ID
- `issue` - Get a single issue by ID
- `project_statuses` - Get all project statuses
- `project_issues` - Get all issues in a project
- `issue_labels` - Get all issue labels
- `issue_states` - Get all available issue states
- `get_viewer` - Get current user information including teams
- `update_project_state` - Update the state of a project
## Architecture
This server follows the Model Context Protocol (MCP) architecture to provide a standardized way to access Linear resources. Key architectural decisions include:
1. **Resource Organization**: Resources are organized by domain in separate files
2. **Error Handling**: Consistent error handling across all resources
3. **Response Format**: Consistent JSON response format
For more detailed information about the architecture, see [adr.md](adr.md).
## Development
```bash
# Run tests
pnpm test
# Build the project
pnpm run build
# Watch for changes
pnpm run watch
# Run with inspector
pnpm run debug
```
For development and testing, you can use the MCP Inspector to interact with the server:
```bash
# Install the MCP Inspector globally
pnpm install -g @modelcontextprotocol/inspector
# Run the server with the inspector
LINEAR_API_KEY=your_api_key_here mcp-inspector /path/to/mcp-server-linear/dist/index.js
# Or using npx
LINEAR_API_KEY=your_api_key_here npx -y @modelcontextprotocol/inspector @mkusaka/mcp-server-linear
```
### Command Line Options
```bash
# Enable logging (logs to linear-mcp.log by default)
pnpm run start -- --debug
# Enable logging with custom log file path
pnpm run start -- --debug --log-file custom-path.log
```
## Contributing
Contributions are welcome! See [adr.md](adr.md) for architecture decisions and project structure.
## License
MIT
