Linear MCP服务器

# 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

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/absolute/path/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

Ask Claude: "List my Linear teams"

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/absolute/path/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/absolute/path/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

Ask Cursor: "List my Linear teams using the MCP tools"

{
  "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": []
    }
  }
}

{
  "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"
      }
    }
  ]
}

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/absolute/path/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/absolute/path/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

// 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

"Check my Linear API quota status"

// Returns:
{
  "warningLevel": "normal",
  "usage": {
    "requestsThisHour": 150,
    "hourlyUsagePercent": 15.0
  },
  "quota": {
    "remainingHour": 850,
    "resetTime": "in 3245s"
  }
}

"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: john@example.com
- 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

# 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

{
  "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"
      }
    }
  }
}

// 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

// 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

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]
  }
}

# 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

ls -lh /path/to/linear-mcp/build/index.js

{
  "args": ["/absolute/path/to/linear-mcp/build/index.js"]  // ✅ Good
  "args": ["./build/index.js"]  // ❌ Won't work
}

# Test API key manually
curl -H "Authorization: Bearer lin_api_your_key" \
  https://api.linear.app/graphql \
  -d '{"query": "{ viewer { name } }"}'

"Check my Linear API rate limit status"

# Clear cache and rebuild
rm -rf build/ node_modules/
npm install
npm run build
npm test

"List my Linear teams"
// Returns team IDs and names