Skip to main content
Deutsch (Deutschland) Español Français Hebrew (Israel) Italiano Português

MCP Server

Heather Hazell
Updated

The LinearB MCP (Model Context Protocol) server lets you interact with your LinearB data through Claude using natural language and prebuilt prompts. Once connected, Claude can call dedicated LinearB tools (metrics, repositories, incidents, teams, PRs, and more) to help you explore delivery, quality, throughput, and DevEx insights directly from your MCP client.

TL;DR

  • Connects Claude to LinearB via the MCP protocol using your LinearB API key.
  • Two setup paths: Claude Desktop + mcp-remote or Claude Code CLI.
  • Exposes LinearB tools (metrics, repositories, incidents, PRs, etc.) for natural-language queries and reports.
  • Includes a Prompt Library with ready-made reports (merge rate, lead time, urgent PRs, release reports, and more).
  • Beta feature — always verify numbers in the LinearB UI before using them for critical decisions.

Overview

The LinearB MCP server is a secure gateway between Claude and your LinearB organization. Once configured, Claude can:

  • Use LinearB-specific tools (e.g. metrics, pull_requests, incidents, teams) to query your data.
  • Run prebuilt prompts from the LinearB Prompt Library (e.g. merge rate, lead time, urgent PR reports).
  • Help leaders, managers, and developers explore patterns in delivery, quality, throughput, DevEx, and incidents.

The MCP server is released as a Beta feature. Behavior and documentation may change before GA.

Before You Begin

  • Required: A valid LinearB API key (organization-scoped).
  • Client options:
    • Claude Desktop with mcp-remote installed, or
    • Claude Code with the claude CLI available.
  • Recommended: Basic familiarity with your OS terminal (macOS, Linux, or Windows).
  • Beta notice: Use with caution in production and validate results in the LinearB UI.

How the MCP Server Works

1. Secure connection via API key

The MCP server authenticates each request from Claude using your LinearB API key. All calls are scoped to your organization and respect your existing data access and permissions.

2. Tools mapped to LinearB data domains

The server exposes a set of tools that map directly to LinearB data domains, such as metrics, repositories, contributors, incidents, and more. Claude uses these tools behind the scenes to answer your prompts.

3. Natural-language querying in Claude

Once connected, you can ask Claude questions like:

  • “Show me cycle time trends for the frontend repo over the last six months.”
  • “List incidents resolved by Team Alpha this week.”
  • “Generate a merge rate report for all backend teams for the previous quarter.”

Claude translates your prompt into MCP tool calls, runs them against the LinearB MCP server, and presents the result.

4. Beta & accuracy considerations

The MCP server is a Beta feature and uses generative AI to interpret your prompts. As a result:

  • Some responses may be incomplete or partially inaccurate.
  • Always verify important numbers (e.g. DORA metrics, team benchmarks) directly in the LinearB Dashboard before using them for official reporting.

Configuring the MCP Server

There are two supported setup options. Choose the one that matches how you use Claude.

Option 1 — Claude Desktop + mcp-remote

Step 1 – Install Node.js

Check if Node.js is installed:

node --version
  • If you see a version (e.g. v18.x.x), you’re good to continue.
  • If not, install Node.js for your OS (e.g. from nodejs.org or via your package manager).

Step 2 – Install mcp-remote 

npm install -g mcp-remote

This installs the mcp-remote CLI globally.

Step 3 – Locate Node and mcp-remote paths

On macOS/Linux, run:

which node
which mcp-remote

On Windows (Command Prompt or PowerShell), run:

where node
where mcp-remote

Save both paths — you will need them in the config file.

Step 4 – Edit the Claude Desktop MCP config

  1. Open Claude Desktop.
  2. Go to Settings → Developer → Edit Config.
  3. Add (or merge) the following JSON into your config:
{
  "mcpServers": {
    "linearb": {
      "command": "FULL_PATH_TO_NODE",
      "args": [
        "FULL_PATH_TO_MCP_REMOTE",
        "https://mcp.linearb.io/mcp",
        "--header",
        "x-api-key: YOUR-API-KEY"
      ]
    }
  }
}

Replace:

  • FULL_PATH_TO_NODE – the value returned by which node or where node.
  • FULL_PATH_TO_MCP_REMOTE – the value returned by which mcp-remote or where mcp-remote.
  • YOUR-API-KEY – your actual LinearB API key.

Step 5 – Save and restart Claude Desktop

Save the config file and restart Claude Desktop. After restart, Claude will list linearb as an available MCP server.

Option 2 — Claude Code CLI

If you use Claude Code, you can register the LinearB MCP server with a single CLI command (no manual JSON edits).

Step 1 – Run the add command

claude mcp add --transport http linearb https://mcp.linearb.io/mcp --header "x-api-key: LINEARB_API_TOKEN"

Replace: LINEARB_API_TOKEN with your actual LinearB API key.

Step 2 – Confirm registration

After running the command, Claude Code registers the linearb MCP server and makes it available for use in your coding environment.

Using the MCP Server

Accessing LinearB prompts in Claude Desktop
  1. Open Claude Desktop.
  2. From the welcome screen or main interface, open the Prompts panel.
  3. Click + and select Add from LinearB Metrics.
  4. LinearB-specific prompts will appear, including merge rate, lead time, urgent PR, and release reports.

Once enabled, you can run these prompts directly from Claude using your connected LinearB data.

Example use cases by persona

Engineering leaders

  • Benchmark delivery, quality, and throughput metrics across teams.
  • Identify best practices from high-performing teams and contributors.
  • Spot systematic inefficiencies (repos, workflows, or teams that lag consistently).
  • Align internal performance metrics with industry benchmarks.

Team leads & managers

  • Surface contributor-level patterns in productivity, quality, and collaboration.
  • Understand review participation and balance of new code vs. rework.
  • Break down coding, reviewing, and deployment times.
  • Use precise data to support coaching conversations and 1:1s.

Executives & cross-functional partners

  • Generate tailored reports from natural-language questions (no dashboard navigation required).
  • Answer ad-hoc questions such as cycle time trends, merge rates, and release outcomes.
  • Filter by teams, contributors, repositories, and date ranges as needed.
Tools exposed by the MCP server

The following tools are available to Claude through the LinearB MCP server:

Tool Description
metrics Engineering metrics with filtering and aggregation.
repositories Repository lookup and information.
contributors Contributor search and details.
releases Release information and tracking.
incidents Incident search and management.
issues Issue tracking and search.
services Service listing and information.
users User search and profiles.
teams Team and group search.
branches Branch search and information.
pull_requests Pull request search and data.
pm_entities Project management entities such as epics, features, and initiatives.

You can use these tools through Claude by asking natural-language questions such as: “Show me the top repositories by merge rate last month” or “List incidents resolved by Team Alpha this week.”

Prompt Library

LinearB provides a Prompt Library with ready-made MCP prompts, including:

  • Merge rate report – Track code delivery velocity and bottlenecks.
  • Lead time report – Measure time from work start to completion.
  • Urgent PR report – Identify and resolve high-priority PRs.
  • Release report – Fetch PRs tied to specific releases.

For a reference of ready-to-use queries, see the LinearB MCP Server Prompt Library (PDF) .

Caution: Important Notes on MCP Usage

The LinearB MCP server is a Beta feature. Behavior and outputs may change before general availability.

Numbers and data outputs from the MCP—like any generative AI results—should be verified for accuracy. To ensure correctness, we recommend reproducing results in the LinearB UI Dashboard before using any MCP-generated metrics for critical decisions.

Troubleshooting

Claude cannot find the “linearb” server
  • Confirm you saved the MCP JSON config (Claude Desktop) or ran the claude mcp add command (Claude Code).
  • Check that FULL_PATH_TO_NODE and FULL_PATH_TO_MCP_REMOTE are correct and executable.
  • Restart Claude after making configuration changes.
Authentication or API key issues
  • Verify that the x-api-key header uses a valid LinearB API key.
  • Check that the key belongs to the correct LinearB organization.
  • If a key was rotated or revoked, update your MCP configuration accordingly.
Unexpected or inaccurate data
  • Re-run the same query directly in the LinearB UI (or via official APIs) to compare results.
  • Adjust your prompt to be more specific about teams, repos, and date ranges.
  • For persistent discrepancies, capture the prompt and response and contact LinearB support.

Related articles