Linear MCP Server

An MCP server for interacting with Linear's API. This server provides a set of tools for managing Linear issues, projects, and teams through Cline.

Setup Guide

$3

1. Clone the repository
2. Install dependencies:
``bash
npm install
`
3. Copy .env.example to .env:
`bash
cp .env.example .env
`

$3

The server supports two authentication methods:

#### Personal Access Token via Environment Variable (Recommended for Dev/Single Users)

1. Go to Linear: Settings > API > OAuth application > "Cline MCP"
2. Under "Developer Token", click "Create & copy token"
3. Select "Application"
4. Add the token to your .env file:
`
LINEAR_ACCESS_TOKEN=your_personal_access_token
`

This method is simple and suitable for testing and development environments.

Optionally, you can use an API key here instead.

#### OAuth Flow (Recommended for production)

1. Create an OAuth application at https://linear.app/settings/api/applications
2. Configure OAuth environment variables in .env:
`
LINEAR_CLIENT_ID=your_oauth_client_id
LINEAR_CLIENT_SECRET=your_oauth_client_secret
LINEAR_REDIRECT_URI=http://localhost:3000/callback
`
3. Use the linear_auth tool to initiate the OAuth flow:
`json
{
"clientId": "your_client_id",
"clientSecret": "your_client_secret",
"redirectUri": "your_redirect_uri"
}
`
4. Follow the authorization URL to grant access
5. Use the linear_auth_callback tool with the authorization code:
`json
{
"code": "authorization_code_from_redirect"
}
`

This method is more secure and recommended for production environments and multi-user scenarios.

$3

1. Build the server:
`bash
npm run build
`
2. Start the server:
`bash
npm start
`

$3

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": "node",
"args": ["/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_ACCESS_TOKEN": "your_personal_access_token_or_api_key"
},
"disabled": false,
"autoApprove": []
}
}
}
`

Available Actions

The server currently supports the following operations:

$3

- ✅ Personal Access Token (PAT) authentication via environment variable
- ✅ OAuth flow authentication
- ✅ Secure token storage

$3

- ✅ Create issues with full field support (title, description, team, project, etc.)
- ✅ Update existing issues (priority, description, etc.)
- ✅ Delete issues (single or bulk deletion)
- ✅ Search issues with filtering
- ✅ Associate issues with projects
- ✅ Create parent/child issue relationships

$3

- ✅ Create projects with associated issues
- ✅ Get project information
- ✅ Associate issues with projects

$3

- ✅ Get team information (with states and workflow details)
- ✅ Access team states and labels

$3

- ✅ Bulk issue creation
- ✅ Bulk issue deletion

$3

- 🚧 Bulk issue updates (parallel processing implemented, needs testing)

Features in Development

The following features are currently being worked on:

$3

- 🚧 Comment functionality (add/edit comments, threading)
- 🚧 Complex search filters
- 🚧 Pagination support for large result sets

$3

- 🚧 Label management (create/update/assign)
- 🚧 Cycle/milestone management

$3

- 🚧 Project template support
- 🚧 Advanced project operations

$3

- 🚧 OAuth flow with automatic token refresh

$3

- 🚧 Rate limiting
- 🚧 Detailed logging
- 🚧 Load testing and optimization

Development

`bash


Install dependencies

npm install

Run tests

npm test

Run integration tests (requires LINEAR_ACCESS_TOKEN)

npm run test:integration

Build the server

npm run build

Start the server

npm start
`

Integration Testing

Integration tests verify that authentication and API calls work correctly:

1. Set up authentication (PAT recommended for testing)
2. Run integration tests:
`bash
npm run test:integration
`

For OAuth testing:
1. Configure OAuth credentials in .env
2. Remove .skip from OAuth tests in src/__tests__/auth.integration.test.ts`
3. Run integration tests