Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
server
✓ import { Server } from '@modelcontextprotocol/sdk/server/index.js'
✗ import { Server } from '@modelcontextprotocol/sdk'
Direct path to server module required; ESM-only since v0.1.0
LinearClient
✓ import { LinearClient } from 'linear-client'
✗ const LinearClient = require('linear-client')
Package is ESM-only in v0.1.0; no CJS support
CallToolResult
✓ import { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
✗ import { CallToolResult } from '@modelcontextprotocol/sdk'
Type import from SDK; path required for tree-shaking
Show how to set up and run a Linear MCP server with Stdio transport, handling tool calls and resource reads.
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { LinearClient } from 'linear-client';
import { CallToolRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
const server = new Server({
name: 'linear-mcp-server',
version: '0.1.0',
});
const linearClient = new LinearClient(process.env.LINEAR_API_KEY ?? '');
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
try {
switch (name) {
case 'linear_create_issue': {
const issue = await linearClient.issue.create({
teamId: args.teamId,
title: args.title,
description: args.description,
priority: args.priority ?? 0,
});
return { content: [{ type: 'text', text: JSON.stringify(issue) }] };
}
case 'linear_search_issues': {
const issues = await linearClient.issues.search(args.query ?? '', { limit: args.limit ?? 10 });
return { content: [{ type: 'text', text: JSON.stringify(issues.nodes) }] };
}
default:
throw new Error(`Unknown tool: ${name}`);
}
} catch (error) {
return { isError: true, content: [{ type: 'text', text: error.message }] };
}
});
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
resources: [
{ uri: 'linear-issue:///{issueId}', name: 'Linear Issue' },
{ uri: 'linear-team:///{teamId}/issues', name: 'Team Issues' },
],
}));
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const uri = request.params.uri;
const match = uri.match(/linear-(issue|team):\/\/(.+)/);
if (!match) throw new Error(`Invalid resource URI: ${uri}`);
const [, type, id] = match;
if (type === 'issue') {
const issue = await linearClient.issue(id);
return { contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(issue) }] };
}
throw new Error('Resource not found');
});
const transport = new StdioServerTransport();
await server.connect(transport);
Errors
Common errors & fixes
Error: LINEAR_API_KEY is not set
The required environment variable LINEAR_API_KEY is missing when the server starts.
fixSet the environment variable before running the server (e.g., export LINEAR_API_KEY=your_key or add to Claude config).
Error: Team not found
The teamId provided to linear_create_issue does not exist or is invalid.
fixVerify the team ID from Linear's settings (https://linear.app/YOUR-TEAM/settings/api) and ensure it's a valid UUID.
Error: Cannot read properties of undefined (reading 'map')
The result of a Linear API call might be undefined when no data is returned.
fixAdd null/undefined checks before accessing properties like .nodes on search results.
Error: Unsupported transport type
The MCP SDK's StdioServerTransport requires Node.js 16+; older versions may not support it fully.
fixEnsure Node.js 16+ is installed (use node --version to check).
Audit
Dependencies
@modelcontextprotocol/sdkrequiredCore MCP protocol implementation required for server functionality
linear-clientrequiredGraphQL client for Linear API interactions