Linear MCP Server - Production Grade
Production-grade MCP server for Linear.app with enterprise resilience, performance optimization, and clean architecture.
Усильте агента
Установка от издателя. Не эндпоинт PlugMCP.
Host a copy with our keys and logs.
В реестре пока нет пакетного релиза. Следуйте README репозитория.
Удалённый URL или команда на вашем компьютере? Чем различаются два способа установки
Запустить на PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
ЗапускОт издателя
Built on the foundation of cline/linear-mcp with 10 major enhancements and 5,116 lines of additional production code.
# Clone the repository
git clone https://github.com/locomotive-agency/linear-mcp.git
cd linear-mcp
# Install dependencies
npm install
# Build the server
npm run build
# Install globally
npm install -g @locomotive/linear-mcp
# Or install locally in your project
npm install @locomotive/linear-mcp
The key will look like: lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
1. Locate your Claude Code config file:
~/.claude.json~/.claude.json%USERPROFILE%\.claude.json2. Add the MCP server configuration:
{
"mcpServers": {
"linear": {
"command": "node",
"args": ["/absolute/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your_key_here"
}
}
}
}
3. Restart Claude Code
4. Verify it's working:
Ask Claude: "List my Linear teams"
1. Locate your Claude Desktop config:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.json2. Add MCP server configuration:
{
"mcpServers": {
"linear": {
"command": "node",
"args": ["/absolute/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your_key_here"
}
}
}
}
3. Restart Claude Desktop
4. Verify:
1. Open Cursor settings:
Cursor → Settings → MCPFile → Preferences → MCP2. Add server configuration:
Create/edit ~/.cursor/mcp.json (macOS/Linux) or %APPDATA%\.cursor\mcp.json (Windows):
{
"mcpServers": {
"linear": {
"command": "node",
"args": ["/absolute/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your_key_here"
}
}
}
}
3. Restart Cursor
4. Verify in Cursor chat:
Ask Cursor: "List my Linear teams using the MCP tools"
1. Locate Cline MCP settings:
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json2. Add server configuration:
{
"mcpServers": {
"linear": {
"command": "node",
"args": ["/absolute/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your_key_here"
},
"disabled": false,
"autoApprove": []
}
}
}
3. Reload VS Code window
4. Verify:
Note: OpenAI doesn't directly support MCP servers, but you can:
Option 1: Use as Local API
Option 2: Use Claude Code as Proxy
Option 3: Direct Integration (requires development) Create an OpenAI plugin/action wrapper around this MCP server.
1. Locate Continue config:
~/.continue/config.json2. Add MCP server to tools section:
{
"tools": [
{
"type": "mcp",
"name": "linear",
"command": "node",
"args": ["/absolute/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your_key_here"
}
}
]
}
3. Restart Continue
1. Create/edit Windsurf MCP config:
~/.windsurf/mcp.json2. Add configuration:
{
"mcpServers": {
"linear": {
"command": "node",
"args": ["/absolute/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your_key_here"
}
}
}
}
3. Restart Windsurf
For any MCP-compatible client:
Configuration Template:
{
"mcpServers": {
"linear": {
"command": "node",
"args": ["/absolute/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_your_key_here"
}
}
}
}
Requirements:
npm run build)build/index.js// Using Claude Code, Claude Desktop, or Cursor
"Create a new Linear issue in the LOCOMOTIVE team:
Title: Implement user authentication
Description: Add OAuth 2.0 authentication with Google and GitHub providers
Priority: High (2)
Estimate: 5 story points"
"Search for all 'In Progress' issues in the LOCOMOTIVE team and update them to 'In Review'"
"Create a new project called 'Q4 2025 Features' with these milestones:
- Alpha Release (Nov 1)
- Beta Release (Nov 15)
- Production (Dec 1)
Then create 5 initial issues for the project."
// MCP server automatically optimizes related queries
"Get the project details, all milestones, and all issues for project ABC-123"
// This uses query batching internally - 1 rate limit slot instead of 3
# Run all tests
npm test
# Run specific test suite
npm test -- rate-limiter.test.ts
# Run tests in watch mode
npm test:watch
# Run integration tests (requires LINEAR_API_KEY)
npm run test:integration
src/
├── auth/ # Modular authentication
│ ├── types.ts # Auth interfaces
│ ├── api-key-auth.ts # API Key implementation
│ ├── oauth-auth.ts # OAuth implementation
│ └── index.ts # Factory/adapter
├── core/
│ ├── handlers/ # Domain handlers with lifecycle hooks
│ ├── middleware/ # Rate limiting, retry logic
│ ├── errors/ # Domain-specific error types
│ └── types/ # TypeScript definitions
├── features/
│ ├── issues/ # Issue management
│ ├── projects/ # Project management
│ ├── teams/ # Team management
│ ├── milestones/ # Milestone management
│ ├── comments/ # Comment management
│ └── monitoring/ # Rate limit monitoring
└── graphql/
├── client.ts # GraphQL client with batching
├── queries.ts # Query definitions
└── mutations.ts # Mutation definitions
Tool: linear_get_rate_limit_status
"Check my Linear API quota status"
// Returns:
{
"warningLevel": "normal",
"usage": {
"requestsThisHour": 150,
"hourlyUsagePercent": 15.0
},
"quota": {
"remainingHour": 850,
"resetTime": "in 3245s"
}
}
linear_create_issueCreate a single issue with full field support (title, description, team, assignee, priority, estimate, project, custom display).
linear_create_issuesBatch operation - Create multiple issues in one API call. ~10x faster than individual creates.
linear_update_issueUpdate any issue field: title, description, assignee, priority, state, project, or milestone.
linear_bulk_update_issuesBatch operation - Update multiple issues with the same changes. Efficient with per-issue error handling.
linear_update_issue_milestoneAssign an issue to a milestone or remove milestone assignment (pass null/empty).
linear_search_issuesSearch issues with advanced filtering: query text, teams, assignees, states, priority. Supports pagination.
Tip: Keep first parameter ≤ 20 for best performance.
linear_delete_issueDelete a single issue by identifier (LOC-123) or UUID.
linear_delete_issuesBatch operation - Delete multiple issues at once.
linear_link_issuesCreate relationships between issues: "blocks", "related", or "duplicate".
linear_unlink_issuesRemove a relationship between issues.
linear_get_issue_commentsGet all comments for an issue, including threaded replies. Supports pagination and archived comments.
linear_create_commentAdd a comment to an issue or create threaded reply. Markdown supported. OAuth apps can set custom display name.
linear_create_project_with_issuesAtomic operation - Create a project and initial issues in one transaction.
Important: teamIds is an array, not a single teamId.
linear_get_projectGet detailed project information with rich text descriptions (documentContent support).
linear_search_projectsSearch for projects by exact name match.
linear_create_project_milestoneCreate a single milestone with name, description, target date, and sort order.
linear_create_project_milestonesBatch operation - Create multiple milestones for a project in one call.
linear_get_project_milestoneGet detailed milestone information including associated issues.
linear_get_project_milestonesList all milestones for a specific project with pagination.
linear_search_project_milestonesSearch milestones with filters: name, project, target date.
linear_update_project_milestoneUpdate milestone properties: name, description, target date, sort order, or move to different project.
linear_delete_project_milestoneDelete a milestone permanently.
linear_get_teamsList all teams with states, labels, and workflow details. Best Practice: Call once at session start and cache team IDs.
linear_get_userGet authenticated user information: ID, name, email, accessible teams. Use: Verify authentication, get user ID for assignments.
linear_get_rate_limit_statusReal-time monitoring of API quota and usage.
Returns:
Automatic Features:
linear_authInitialize OAuth flow (OAuth apps only). Most users should use API Key authentication instead.
linear_auth_callbackHandle OAuth authorization callback (OAuth apps only).
Priority Values:
0 = None1 = Urgent 🔴2 = High 🟠3 = Medium 🟡4 = Low 🔵Common State Names:
Estimate Points (story points):
"List my Linear teams"
→ Returns team names, keys, and UUIDs needed for other operations
"Create a Linear issue:
- Team: LOCOMOTIVE
- Title: Implement authentication system
- Description: Add OAuth 2.0 with Google and GitHub providers
- Priority: High (2)
- Estimate: 8 points
- Assignee: [email protected]
- Project: Phase 2 Features"
"Create 10 issues for the new feature:
1. Research requirements (estimate: 2)
2. Design architecture (estimate: 3)
3. Implement backend (estimate: 8)
..."
→ Uses linear_create_issues for efficient batch creation
"Find all urgent priority issues that are in Todo or In Progress state for the LOCOMOTIVE team"
→ Uses linear_search_issues with filters:
- teamIds: ["team-uuid"]
- states: ["Todo", "In Progress"]
- priority: 1
// Ask Claude Code, Cursor, or Claude Desktop:
"Create a new Linear project called 'Website Redesign' in the DESIGN team with these milestones:
1. Research & Planning (target: Dec 1, 2025)
2. Design Phase (target: Dec 15, 2025)
3. Development (target: Jan 15, 2026)
4. Launch (target: Feb 1, 2026)
Then create 3 initial issues:
- Conduct user research (milestone: Research & Planning)
- Create design mockups (milestone: Design Phase)
- Setup development environment (milestone: Development)"
"Find all issues with priority 'Urgent' in the 'Todo' state and move them to 'In Progress'"
// Uses:
// 1. linear_search_issues with filters
// 2. linear_bulk_update_issues for efficient batch update
"Create 3 related issues for the authentication feature:
1. Backend API (blocks the other two)
2. Frontend UI (blocked by #1)
3. Testing (related to both)
Link them appropriately."
// Uses:
// 1. linear_create_issues (batch)
// 2. linear_link_issues (create relationships)
"Check my Linear API quota and warn me if it's above 80%"
// Uses:
// linear_get_rate_limit_status
// Returns real-time quota with warning levels
Create a .env file (optional):
# Authentication (choose one)
LINEAR_API_KEY=lin_api_your_key_here
# Or OAuth (not fully implemented)
LINEAR_CLIENT_ID=your_client_id
LINEAR_CLIENT_SECRET=your_client_secret
LINEAR_REDIRECT_URI=http://localhost:3000/callback
# Optional: Rate limiting (defaults shown)
RATE_LIMIT_MAX_PER_HOUR=1000
RATE_LIMIT_MAX_PER_MINUTE=100
RATE_LIMIT_SAFETY_THRESHOLD=0.9 # Queue at 90%
# Optional: Retry configuration
RETRY_MAX_ATTEMPTS=5
RETRY_INITIAL_DELAY_MS=100
Configure via MCP settings:
{
"mcpServers": {
"linear": {
"command": "node",
"args": ["/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_API_KEY": "your_key",
"RATE_LIMIT_SAFETY_THRESHOLD": "0.85",
"RETRY_MAX_ATTEMPTS": "3"
}
}
}
}
Automatically batches related queries for efficiency:
// When you ask:
"Get project details, milestones, and all issues for Project X"
// The server automatically batches these queries:
// - Uses 1 rate limit slot instead of 3
// - Executes with coordinated error handling
// - Returns all results together
Extensible handler system for cross-cutting concerns:
// Built-in hooks:
- Logging hook: Logs all operations automatically
- Metrics hook: Tracks duration and success rates
// Easy to add custom hooks:
- Caching hook: Cache frequently accessed data
- Audit hook: Track all operations for compliance
Type-safe error handling with structured logging:
try {
await linear.createIssue({ priority: 99 }); // Invalid
} catch (error) {
if (error instanceof ValidationError) {
console.log(`Field: ${error.field}`); // "priority"
console.log(`Value: ${error.value}`); // 99
console.log(`Valid: ${error.validValues}`); // [0,1,2,3,4]
}
}
// Structured logging:
{
"timestamp": "2025-10-29T...",
"level": "ERROR",
"type": "ValidationError",
"code": "VALIDATION_INVALID_VALUE",
"message": "Invalid priority value",
"context": {
"field": "priority",
"value": 99,
"validValues": [0,1,2,3,4]
}
}
Added Code: 5,116 lines beyond original
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Watch mode
npm test:watch
# Type checking
npm run type-check
linear-mcp/
├── src/
│ ├── auth/ # Authentication (modular)
│ ├── core/ # Core systems
│ ├── features/ # Domain features
│ ├── graphql/ # GraphQL client
│ └── __tests__/ # Test suites
├── build/ # Compiled output
├── docs/ # Documentation
│ ├── IMPROVEMENTS.md
│ ├── PROJECT-COMPLETE.md
│ └── MIGRATION-PLAN.md
└── package.json
See CONTRIBUTING.md for:
Check build exists:
ls -lh /path/to/linear-mcp/build/index.js
Verify config path is absolute (not relative):
{
"args": ["/absolute/path/to/linear-mcp/build/index.js"] // ✅ Good
"args": ["./build/index.js"] // ❌ Won't work
}
Check Linear API key:
# Test API key manually
curl -H "Authorization: Bearer lin_api_your_key" \
https://api.linear.app/graphql \
-d '{"query": "{ viewer { name } }"}'
Symptom: "Authentication not initialized" or "Unauthorized"
Solutions:
Symptom: Console warnings about approaching limits
This is normal! The monitoring system warns you at:
Action: The rate limiter automatically queues requests, no action needed.
To monitor:
"Check my Linear API rate limit status"
# Clear cache and rebuild
rm -rf build/ node_modules/
npm install
npm run build
npm test
Verify server is running:
ls -lh build/index.js)See Linear API Documentation for field details.
Common Parameters:
teamId - Team UUID (required for most operations)priority - 0=None, 1=Urgent, 2=High, 3=Medium, 4=LowstateId - Workflow state UUIDestimate - Story points (typically 1, 2, 3, 5, 8)Get Team ID:
"List my Linear teams"
// Returns team IDs and names
This project builds upon the excellent foundation of cline/linear-mcp.
Original Authors: Cline team Enhanced By: LOCOMOTIVE Agency
See ATTRIBUTION.md for detailed credits.
MIT License - see LICENSE file for details.
See CONTRIBUTING.md for contribution guidelines.
✅ Rate limiting ensures you never hit API limits ✅ Automatic retry recovers from 90%+ of failures ✅ Real-time monitoring prevents surprises
✅ Query batching reduces API calls by 67% ✅ Optimized operations for complex workflows ✅ Efficient batch processing
✅ Modular architecture (easy to extend) ✅ Type-safe error handling ✅ Comprehensive tests (203 passing) ✅ Zero breaking changes (backward compatible)
✅ Lifecycle hooks for logging, metrics, caching ✅ Structured error logging ✅ Observable operations ✅ Production-ready
Version: 2.0.0 Status: Production Ready 🚀 Built with: ❤️ and ZERO MOCK compliance
Production-grade MCP server for Linear.app with enterprise resilience, performance optimization, and clean architecture.
Инструменты
Списка инструментов пока нет. У удалённых серверов он появляется после первой проверки состояния.
FAQ
Скопируйте на этой странице конфигурацию stdio для Cursor, Claude Desktop, Claude Code или VS Code. Она использует установку издателя, а не прокси PlugMCP.
В этой записи не указано обязательных переменных окружения.
Linear работает локально через stdio.
Последняя проверка: 2026-10-28. Production-grade MCP server for Linear.app with enterprise resilience, performance optimization, and clean architecture.