Linear MCP Adapter Service

This project implements an MCP server, engineered in Go, designed to bridge standard Model Context Protocol calls to the official Linear REST API.

Core Capabilities

• Provisioning, modifying, and locating issues within Linear.
• Fetching assignments for specific personnel.
• Appending explanatory comments to existing tickets.
• Acquiring metadata regarding Linear teams.
• Adhering to Linear's API rate constraints through built-in throttling.

Prerequisites

• Minimum Go runtime version: 1.23
• A valid Linear API authorization token

Acquisition

Binary Distribution

Pre-compiled executables for major operating systems (Linux, macOS, Windows) are hosted on the project's GitHub Releases page.

1. Secure the correct executable for your operating environment.

2. Ensure execution permissions (for Unix-like systems):

   bash chmod +x linear-mcp-go-*

3. Refer to the Usage section for operational instructions.

Scripted Fetching

Use this snippet to automatically fetch the latest Linux binary and configure it for an AI agent workflow (e.g., 'cline'):

# Retrieve URL for the latest stable release asset targeting Linux
RELEASE_INFO=$(curl -s https://api.github.com/repos/geropl/linear-mcp-go/releases/latest)
DOWNLOAD_LINK=$(echo $RELEASE_INFO | jq -r '.assets[] | select(.name | contains("linux")) | .browser_download_url')
curl -L -o ./linear-mcp-go $DOWNLOAD_LINK
chmod +x ./linear-mcp-go

# Initialize configuration for the Cline tool
./linear-mcp-go setup --tool=cline

Operational Guide

Version Query

Verify the installed version and associated build metadata:

./linear-mcp-go version

Launching the Service

1. Define the Linear API key environment variable:

   bash export LINEAR_API_KEY=your_super_secret_key

2. Start the MCP listener:

   ```bash

   Default: Read-only operation mode

   ./linear-mcp-go serve

   Enable write/mutation capabilities

   ./linear-mcp-go serve --write-access ```

The adapter will then await MCP commands transmitted via standard input/output.

AI Assistant Integration (setup command)

The setup utility streamlines provisioning and configuration across various AI orchestration layers. Note: While setup often requires the API key, the 'Ona' agent is an exception for this step.

# Standard setup (assumes LINEAR_API_KEY is exported)
./linear-mcp-go setup

# Setup authorizing mutations
./linear-mcp-go setup --write-access

# Pre-authorize all read operations automatically
./linear-mcp-go setup --auto-approve=allow-read-only

# Pre-authorize specific functions
./linear-mcp-go setup --auto-approve=linear_get_issue,linear_search_issues

# Configure for a different target client (currently only 'cline' is supported)
./linear-mcp-go setup --tool=cline

This command sequence performs: 1. Verification of the binary's presence. 2. Placement of the binary into the system's expected tool directory. 3. Updating the designated AI client's configuration file. 4. Applying requested automatic permissions for specific tools.

The --auto-approve flag dictates which functions are implicitly trusted by the client:

• allow-read-only: Approves linear_search_issues, linear_get_user_issues, linear_get_issue, linear_get_teams.
• tool1,tool2,...: A custom, comma-separated list of functions to trust.

By default, the service operates restrictively (read-only), disabling mutation functions: * linear_create_issue * linear_update_issue * linear_add_comment

These require enabling write access via the --write-access=true flag upon server launch.

Exposed Functions (Tools)

linear_create_issue

Instantiates a fresh issue within a Linear team.

Arguments: - title (Mandatory): Title text for the ticket. - team (Mandatory): Identifier for the target team (key, UUID, or name). - description: Detailed body content. - priority: Numerical priority level (0 to 4). - status: Desired initial status. - parentIssue: ID for creating a hierarchical sub-issue. - labels: Comma-separated list of label identifiers.

linear_update_issue

Modifies attributes of an existing ticket.

Arguments: - id (Mandatory): Unique identifier of the issue. - title: New subject line. - description: Revised content. - priority: Revised priority value (0-4). - status: New state.

linear_search_issues

Executes advanced queries against the issue database.

Arguments: - query: Textual search across titles and bodies. - teamId: Filter results to a specific team ID. - status: Filter by textual status name (e.g., 'In Progress'). - assigneeId: Filter by the responsible user's ID. - labels: Filter using a list of label names. - priority: Filter by urgency level (1=Highest, 4=Lowest). - estimate: Filter by story point value. - includeArchived: Boolean flag to search deprecated issues (defaults to false). - limit: Maximum count of records to retrieve (default: 10).

linear_get_user_issues

Fetches tickets assigned to a user, optionally the currently authenticated user if no ID is provided.

Arguments: - userId: Identifier of the user. If omitted, the token owner's tickets are returned. - includeArchived: Boolean to include retired tickets. - limit: Maximum number of tickets to return (default: 50).

linear_get_issue

Retrieves the complete data payload for a single issue.

Arguments: - issueId (Mandatory): The unique system ID of the target issue.

linear_add_comment

Posts a textual note onto a designated ticket.

Arguments: - issueId (Mandatory): Target issue identifier. - body (Mandatory): The comment content, formatted in Markdown. - createAsUser: Optional display name override for the author. - displayIconUrl: Optional URL for a custom avatar.

linear_get_teams

Lists available teams, optionally filtering by name substring.

Arguments: - name: String fragment used to match against team display names.

Testing Protocol

Testing relies on go-vcr fixtures, simulating API interactions against a dedicated test environment (https://linear.app/linear-mcp-go-test).

Running Standard Tests

Execute all existing recorded test scenarios:

go test -v ./... 

Replicating Test Scenarios (Recording New Fixtures):

Requires a configured LINEAR_API_KEY for live interaction.

To update tests that do not modify remote state:

go test -v -record=true ./... 

To re-run and capture tests that perform state modifications (use with caution):

go test -v -recordWrites=true ./... 

To update saved .golden comparison files:

go test -v -golden=true ./... 

Distribution Procedure

Release automation is managed via GitHub Actions, centered around the ServerVersion constant defined in pkg/server/server.go.

Automated Build and CI

1. Continuous testing runs on every push to main and for all pull requests.
2. Tagging the repository with a pattern matching v* (e.g., v2.0.1) triggers the automated release workflow.
3. Binaries are compiled for Linux, macOS, and Windows, embedded with build artifacts (commit hash and compilation timestamp).

Manual Release Initiation

Prerequisite: Version tag creation must happen only against a finalized main branch state.

1. Version Bump: Increment ServerVersion in pkg/server/server.go. go // ServerVersion indicates the current adapter release iteration ServerVersion = "2.0.0"

2. Submit for Review: Create a Pull Request for the version update to ensure vetting and successful CI checks.

3. Merge: Integrate the changes into the primary branch.

4. Tag and Push: Create and publish the corresponding Git tag locally: ```bash git checkout main git pull origin main

   Create and publish the tag matching the version constant

   git tag v2.0.0 git push origin v2.0.0 ```

5. Workflow Execution: The GitHub Action workflow automatically:

   • Compiles platform-specific executables.
   • Generates a GitHub Release associated with the tag.
   • Attaches the compiled artifacts to the release package.

Version Reporting

The version utility reports three key pieces of data: - Version: Value sourced from the ServerVersion constant. - Git commit: The SHA injected during the build process. - Build date: The timestamp recorded at compilation.

Development builds missing this metadata will show 'unknown' for commit and date fields.

Licensing

This software is distributed under the MIT License.

== Overview == Business management apparatus encompasses the entire spectrum of systems, applications, procedural controls, analytical methods, and other mechanisms employed by organizations to successfully navigate volatile market conditions, maintain competitive standing, and enhance operational effectiveness.

== Functional Classification == These instruments can be categorized based on their departmental application or functional intent, such as tools for strategic mapping, process governance, record-keeping, human capital management, decision support, or performance oversight. A functional decomposition includes:

• Mechanisms for data ingestion and integrity verification across all business units.
• Systems designed for monitoring and optimizing operational workflows.
• Platforms aggregating data for consolidated reporting and executive judgment.

Modern business tooling has undergone rapid transformation fueled by technological acceleration, making optimal selection a complex challenge. This complexity is driven by perpetual objectives: cost reduction, revenue growth, deep customer insight acquisition, and precise product delivery matching demand specifications. In this context, managerial emphasis should shift from adopting the newest solution to strategically evaluating and customizing management instruments to organizational requirements, rather than forcing organizational alignment to the tool's inherent design.

== Prevalent Instruments == Data from a 2013 Bain & Company assessment illustrated global usage patterns of management tools, reflecting regional priorities shaped by economic climates. The top instruments identified were:

• Strategic blueprinting
• Customer relationship management (CRM)
• Personnel sentiment analysis
• Comparative performance analysis (Benchmarking)
• Performance measurement frameworks (Balanced Scorecard)
• Identification of core organizational strengths
• Offshoring/Outsourcing strategies
• Organizational transition programs
• Logistics and procurement oversight (SCM)
• Articulating organizational purpose (Mission/Vision statements)
• Consumer group differentiation
• Comprehensive quality assurance programs

== Business Software Applications == Software—a collection of programs utilized by personnel to execute diverse organizational tasks—is termed business software. These applications aim to amplify productivity, quantify output metrics, and ensure accuracy in operational execution. The evolution stretches from initial Management Information Systems (MIS) to comprehensive Enterprise Resource Planning (ERP), later incorporating CRM functionalities, culminating in today's cloud-centric business administration suites. While IT investment correlates with organizational success, two factors remain critical for value realization: the proficiency of the implementation and the diligence applied in tool selection and modification.