Content
# Linear MCP Server
A Model Context Protocol (MCP) server for Linear, written in Go. This server provides tools for interacting with the Linear API through the MCP protocol.
## Features
- Create, update, and search Linear issues
- Get issues assigned to a user
- Add comments to issues and reply to existing comments
- **URL-aware comment operations** - paste Linear comment URLs directly, no manual ID extraction needed
- Retrieve team information
- Rate-limited API requests to respect Linear's API limits
## Prerequisites
- Go 1.23 or higher
- Linear API key
## Installation
### From Releases
Pre-built binaries are available for Linux, macOS, and Windows on the [GitHub Releases page](https://github.com/geropl/linear-mcp-go/releases).
1. Download the appropriate binary for your platform
2. Make it executable (Linux/macOS):
```bash
chmod +x linear-mcp-go-*
```
3. Run the binary as described in the Usage section
### Automated
```
# Download linux binary for the latest release
RELEASE=$(curl -s https://api.github.com/repos/geropl/linear-mcp-go/releases/latest)
DOWNLOAD_URL=$(echo $RELEASE | jq -r '.assets[] | select(.name | contains("linux")) | .browser_download_url')
curl -L -o ./linear-mcp-go $DOWNLOAD_URL
chmod +x ./linear-mcp-go
# Setup the mcp server (.gitpod.yml, dotfiles repo, etc.)
./linear-mcp-go setup --tool=cline
```
## Usage
### Checking Version
To check the version of the Linear MCP server:
```bash
./linear-mcp-go version
```
This will display the version, git commit, and build date information.
### Running the Server
1. Set your Linear API key as an environment variable:
```bash
export LINEAR_API_KEY=your_linear_api_key
```
2. Run the server:
```bash
# Run in read-only mode (default)
./linear-mcp-go serve
# Run with write access enabled
./linear-mcp-go serve --write-access
```
The server will start and listen for MCP requests on stdin/stdout.
### Setting Up for AI Assistants
The `setup` command automates the installation and configuration process for various AI assistants:
```bash
# Set your Linear API key as an environment variable
# Only exception: Ona does not require this for setup!
export LINEAR_API_KEY=your_linear_api_key
# Set up for Cline (default)
./linear-mcp-go setup
# Set up with write access enabled
./linear-mcp-go setup --write-access
# Set up with auto-approval for read-only tools
./linear-mcp-go setup --auto-approve=allow-read-only
# Set up with specific tools auto-approved
./linear-mcp-go setup --auto-approve=linear_get_issue,linear_search_issues
# Set up with write access and auto-approval for read-only tools
./linear-mcp-go setup --write-access --auto-approve=allow-read-only
# Set up for a different tool (only "cline" supported for now)
./linear-mcp-go setup --tool=cline
```
This command:
1. Checks if the Linear MCP binary is already installed
2. Copies the current binary to the installation directory if needed
3. Configures the AI assistant to use the Linear MCP server
4. Sets up auto-approval for specified tools if requested
The `--auto-approve` flag can be used to specify which tools should be auto-approved in the Cline configuration:
- `--auto-approve=allow-read-only`: Auto-approves all read-only tools (`linear_search_issues`, `linear_get_user_issues`, `linear_get_issue`, `linear_get_teams`)
- `--auto-approve=tool1,tool2,...`: Auto-approves the specified comma-separated list of tools
Currently supported AI assistants:
- Cline (VSCode extension)
By default, the server runs in read-only mode, which means the following tools are disabled:
- `linear_create_issue`
- `linear_update_issue`
- `linear_add_comment`
- `linear_reply_to_comment`
- `linear_update_issue_comment`
To enable these tools, use the `--write-access=true` flag.
## Available Tools
### linear_create_issue
Creates a new Linear issue with specified details. **Supports creating parent-child relationships** (sub-issues) and assigning labels.
**Parameters:**
- `title` (required): Issue title
- `team` (required): Team identifier (key, UUID or name)
- `description`: Issue description
- `priority`: Priority. Accepts: 0/'no priority', 1/'urgent', 2/'high', 3/'medium', 4/'low'
- `status`: Issue status
- `makeSubissueOf`: **Create a sub-issue by specifying the parent issue ID or identifier** (e.g., 'TEAM-123'). This establishes a parent-child relationship in Linear.
- `labels`: Optional comma-separated list of label IDs or names to assign
- `project`: Optional project identifier (ID, name, or slug) to assign the issue to
**Example: Creating a sub-issue**
```json
{
"title": "Implement login form validation",
"team": "ENG",
"makeSubissueOf": "ENG-42",
"description": "Add client-side validation for the login form"
}
```
### linear_update_issue
Updates an existing Linear issue's properties.
**Parameters:**
- `id` (required): Issue ID
- `title`: New title
- `description`: New description
- `priority`: Priority. Accepts: 0/'no priority', 1/'urgent', 2/'high', 3/'medium', 4/'low'
- `status`: New status
### linear_search_issues
Searches Linear issues using flexible criteria.
**Parameters:**
- `query`: Optional text to search in title and description
- `teamId`: Filter by team ID
- `status`: Filter by status name (e.g., 'In Progress', 'Done')
- `assigneeId`: Filter by assignee's user ID
- `labels`: Filter by label names (comma-separated)
- `priority`: Priority. Accepts: 0/'no priority', 1/'urgent', 2/'high', 3/'medium', 4/'low'
- `estimate`: Filter by estimate points
- `includeArchived`: Include archived issues in results (default: false)
- `limit`: Max results to return (default: 10)
### linear_get_user_issues
Retrieves issues assigned to a specific user or the authenticated user.
**Parameters:**
- `userId`: Optional user ID. If not provided, returns authenticated user's issues
- `includeArchived`: Include archived issues in results
- `limit`: Maximum number of issues to return (default: 50)
### linear_get_issue
Retrieves a single Linear issue by its ID.
**Parameters:**
- `issueId` (required): ID of the issue to retrieve
### linear_add_comment
Adds a comment to an existing Linear issue. Supports replying to existing comments by passing a comment identifier in the `thread` parameter.
**Parameters:**
- `issue` (required): ID or identifier (e.g., 'TEAM-123') of the issue to comment on
- `body` (required): Comment text in markdown format
- `thread`: Optional comment identifier to reply to. Accepts: full Linear comment URL, UUID, shorthand (comment-abc123), or hash (abc123). Creates a threaded reply instead of a top-level comment.
- `createAsUser`: Optional custom username to show for the comment
**URL Support:** You can pass a full Linear comment URL (e.g., `https://linear.app/.../issue/TEST-10/...#comment-abc123`) directly to the `thread` parameter. The tool automatically resolves URLs to UUIDs before calling the API.
### linear_reply_to_comment
Convenience tool for replying to an existing comment. Automatically resolves the issue from the comment, so you only need to provide the comment identifier and reply text.
**Parameters:**
- `thread` (required): Comment to reply to. Accepts: full Linear comment URL, UUID, shorthand (comment-abc123), or hash (abc123)
- `body` (required): Reply text in markdown format
- `createAsUser`: Optional custom username to show for the reply
**Why use this tool?** When you have a comment URL or ID and want to reply, this tool is simpler than `linear_add_comment` because you don't need to specify the issue separately. The tool automatically looks up the issue from the comment.
### linear_get_issue_comments
Retrieves comments for a Linear issue with support for pagination and thread navigation.
**Parameters:**
- `issue` (required): ID or identifier (e.g., 'TEAM-123') of the issue to retrieve comments for
- `thread`: Optional UUID of a parent comment to retrieve its replies. If not provided, returns top-level comments
- `limit`: Maximum number of comments to return (default: 10)
- `after`: Cursor for pagination, to get comments after this point
**Use Cases:**
- View all comments on an issue
- Navigate comment threads by passing a comment UUID in the `thread` parameter
- Get comment UUIDs for replying (though with URL support in `linear_add_comment`, this is less necessary)
### linear_update_issue_comment
Updates an existing comment on a Linear issue.
**Parameters:**
- `comment` (required): Comment identifier to update. Accepts: full Linear comment URL, UUID, shorthand (comment-abc123), or hash (abc123)
- `body` (required): New comment text in markdown format
**URL Support:** Like other comment tools, this accepts full Linear comment URLs and automatically resolves them to UUIDs.
### linear_get_teams
Retrieves Linear teams with an optional name filter.
**Parameters:**
- `name`: Optional team name filter. Returns teams whose names contain this string.
## Test
Tests are implemented using [`go-vcr`](https://github.com/dnaeon/go-vcr), and executed against https://linear.app/linear-mcp-go-test.
### Execute tests
Using the existing recordings (cassettes):
```
go test -v ./...
```
#### Re-recording test:
Requires `TEST_LINEAR_API_KEY` to be set for the test workspace.
```
go test -v -record=true ./...
```
This will update all tests that don't alter remote state.
```
go test -v -recordWrites=true ./...
```
This will re-run all tests, including some that might alter the outcome of other tests cases, which might require further manual work to adjust.
```
go test -v -golden=true ./...
```
Updates all .golden fields.
## Release Process
The project uses GitHub Actions for automated testing and releases. The version is managed through the `ServerVersion` constant in `pkg/server/server.go`.
### Automated Testing and Building
1. All pushes to the main branch and pull requests are automatically tested
2. When a tag matching the pattern `v*` (e.g., `v1.0.0`) is pushed, a new release is automatically created
3. Binaries for Linux, macOS, and Windows are built and attached to the release with build-time information (git commit and build date)
### Creating a New Release
**Important**: Version tags should only be created against the `main` branch after all changes have been merged.
1. **Update the version**: Modify the `ServerVersion` constant in `pkg/server/server.go`
```go
// ServerVersion is the version of the MCP server
ServerVersion = "1.13.0"
```
2. **Create a PR**: Submit the version update as a pull request to ensure it goes through review and testing
3. **Merge to main**: Once the PR is approved and merged to the main branch
4. **Create and push the release tag**:
```bash
# Ensure you're on the latest main branch
git checkout main
git pull origin main
# Create and push the tag (must match the version in server.go)
git tag v1.13.0
git push origin v1.13.0
```
5. **Automated release**: The GitHub Actions workflow will automatically:
- Build binaries for all platforms with proper version information
- Create a GitHub release with the tag
- Attach the compiled binaries to the release
### Version Information
The `version` command displays:
- **Version**: Read from `ServerVersion` constant in `pkg/server/server.go`
- **Git commit**: Injected at build time from the current commit hash
- **Build date**: Injected at build time with the current timestamp
For development builds, git commit and build date will show "unknown".
## License
MIT
