Linear

Linear MCP Server

Uma implementação de servidor Model Context Protocol (MCP) que fornece acesso ao sistema de rastreamento de issues do Linear por meio de uma interface padronizada.

Recursos

• Criar novas issues e subissues com suporte a labels
• Recuperar a lista de projetos do Linear
• Recuperar as atualizações de projetos
• Criar uma nova atualização de projeto com status de saúde
• Atualizar issues existentes com modificação completa de campos
• Excluir issues com validação
• Auto-atribuir issues usando a palavra-chave 'me'
• Busca avançada com os poderosos recursos de filtragem do Linear
• Filtrar issues por ciclo (atual, próximo, anterior ou ciclo específico por UUID ou número)
• Adicionar comentários a issues com suporte a markdown
• Consultar issues do Linear por ID ou chave com relacionamentos opcionais
• Buscar issues usando consultas personalizadas com metadados aprimorados
• Operações type-safe usando o SDK oficial do Linear
• Tratamento abrangente de erros
• Tratamento de limite de taxa
• Transformação limpa de dados
• Rastreamento de relacionamentos pai/filho com herança de equipe
• Gerenciamento e sincronização de labels

Pré-requisitos

• Runtime Bun (v1.0.0 ou superior)
• Conta Linear com acesso à API

Variáveis de Ambiente

LINEAR_API_KEY=your_api_key  # Your Linear API token

Instalação e Configuração

1. Clone o repositório:

git clone [repository-url]
cd linear-mcp

2. Instale as dependências e faça o build:

bun install
bun run build

3. Configure o servidor MCP:

Edite o arquivo de configuração apropriado:

macOS:

• Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

• Cline: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Claude Desktop: %APPDATA%\Claude Desktop\claude_desktop_config.json

Linux:

• Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Claude Desktop: infelizmente ainda não existe

Adicione a seguinte configuração sob o objeto mcpServers:

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

4. Reinicie o servidor MCP.

Nas configurações de MCP do Cline, reinicie o servidor MCP. Reinicie o Claude Desktop para carregar o novo servidor MCP.

Desenvolvimento

Execute o servidor de desenvolvimento:

bun run dev

Compile o projeto:

bun run build

Ferramentas MCP Disponíveis

Para exemplos detalhados de uso de todas as ferramentas, consulte USAGE.md.

create_issue

Crie uma nova issue ou subissue do Linear.

Esquema de Entrada:

{
  "teamId": "string",     
  "title": "string",      
  "description": "string",
  "parentId": "string",   
  "status": "string",
  "priority": "number",   
  "assigneeId": "string | 'me'",
  "labelIds": ["string"]  
}

update_issue

Atualize uma issue existente do Linear.

Esquema de Entrada:

{
  "issueId": "string",    
  "title": "string",
  "description": "string",
  "status": "string",     // Expects status NAME (e.g., "In Progress"). Must be valid for the issue's team.
  "priority": "number",   // Expects 0 (None) to 4 (Low).
  "assigneeId": "string | 'me'",
  "labelIds": ["string"],
  "cycleId": "string"
}

get_issue

Obtenha informações detalhadas sobre uma issue específica do Linear com relacionamentos opcionais.

Esquema de Entrada:

{
  "issueId": "string",
  "includeRelationships": "boolean"  
}

search_issues

Busque issues do Linear usando uma string de consulta e filtros avançados. Suporta os poderosos recursos de filtragem do Linear.

Esquema de Entrada:

{
  "query": "string",
  "includeRelationships": "boolean",
  "filter": {
    "title": { "contains": "string", "eq": "string", ... },
    "description": { "contains": "string", "eq": "string", ... },
    "priority": { "gte": "number", "lt": "number", ... },
    "estimate": { "eq": "number", "in": ["number"], ... },
    "dueDate": { "lt": "string", "gt": "string", ... },
    "createdAt": { "gt": "P2W", "lt": "2024-01-01", ... },
    "updatedAt": { "gt": "P1M", ... },
    "completedAt": { "null": true, ... },
    "assignee": { "id": { "eq": "string" }, "name": { "contains": "string" } },
    "creator": { "id": { "eq": "string" }, "name": { "contains": "string" } },
    "team": { "id": { "eq": "string" }, "key": { "eq": "string" } },
    "state": { "type": { "eq": "started" }, "name": { "eq": "string" } },
    "labels": { "name": { "in": ["string"] }, "every": { "name": { "eq": "string" } } },
    "project": { "id": { "eq": "string" }, "name": { "contains": "string" } },
    "and": [{ /* filters */ }],
    "or": [{ /* filters */ }],
    "assignedTo": "string | 'me'",
    "createdBy": "string | 'me'"
  },
  "projectId": "string",
  "projectName": "string"
}

Comparadores Suportados:

• Campos de string: eq, neq, in, nin, contains, startsWith, endsWith (mais variantes sem diferenciar maiúsculas/minúsculas)
• Campos numéricos: eq, neq, lt, lte, gt, gte, in, nin
• Campos de data: eq, neq, lt, lte, gt, gte (suporta durações ISO 8601)

get_teams

Obtenha uma lista de equipes do Linear com filtragem opcional por nome/chave.

Esquema de Entrada:

{
  "nameFilter": "string"  
}

delete_issue

Exclua uma issue existente do Linear.

Esquema de Entrada:

{
  "issueId": "string"
}

create_comment

Crie um novo comentário em uma issue do Linear.

Esquema de Entrada:

{
  "issueId": "string",
  "body": "string"
}

get_projects

Obtenha uma lista de projetos do Linear com filtragem opcional por nome e paginação.

Esquema de Entrada:

{
  "nameFilter": "string",
  "includeArchived": "boolean",
  "first": "number",
  "after": "string"
}

get_project_updates

Obtenha atualizações de projeto para um determinado ID de projeto com parâmetros de filtragem opcionais.

Esquema de Entrada:

{
  "projectId": "string",
  "includeArchived": "boolean",
  "first": "number",
  "after": "string",
  "createdAfter": "string",
  "createdBefore": "string",
  "userId": "string | 'me'",
  "health": "string"
}

create_project_update

Crie uma nova atualização para um projeto do Linear.

Esquema de Entrada:

{
  "projectId": "string",
  "body": "string",
  "health": "onTrack | atRisk | offTrack",
  "isDiffHidden": "boolean"
}

Detalhes Técnicos

• Construído com TypeScript em modo estrito
• Usa o SDK oficial do Linear (@linear/sdk)
• Usa o SDK MCP (@modelcontextprotocol/sdk 1.4.0)
• Autenticação via tokens de API
• Tratamento abrangente de erros
• Considerações sobre limite de taxa
• Runtime Bun para melhor desempenho
• Módulos ESM em todo o projeto
• Sistema de build Vite
• Operações type-safe
• Recursos de limpeza de dados:
  • Extração de menções a issues (formato ABC-123)
  • Extração de menções a usuários (formato @username)
  • Limpeza de conteúdo Markdown
  • Otimização de conteúdo para contexto de IA
• Suporte a auto-atribuição:
  • Resolução automática do usuário atual
  • Suporte à palavra-chave 'me' em operações de criação/atualização
  • Cache eficiente de IDs de usuário
• Recursos avançados de busca:
  • Filtragem abrangente com a API do Linear
  • Suporte a todos os comparadores de campos
  • Filtragem por relacionamentos
  • Operadores lógicos (and, or)
  • Filtragem por data relativa
  • Filtro por responsável/criador (incluindo a si mesmo)
  • Suporte a IDs de usuário específicos
  • Filtragem de projetos por ID ou nome
  • Otimização eficiente de consultas
• Recursos de gerenciamento de projetos:
  • Listagem de projetos com filtragem e paginação
  • Criação de atualizações de projeto com rastreamento de status de saúde
  • Recuperação de atualizações de projeto com opções de filtragem

Tratamento de Erros

O servidor implementa uma estratégia abrangente de tratamento de erros:

• Detecção de erros de rede e mensagens apropriadas
• Tratamento de códigos de status HTTP
• Mensagens de erro detalhadas com códigos de status
• Registro de detalhes de erro no console
• Validação de entrada para todos os parâmetros
• Validação e sincronização de labels
• Propagação segura de erros pelo protocolo MCP
• Detecção e tratamento de limite de taxa
• Tratamento de erros de autenticação
• Tratamento de consultas inválidas
• Validação de herança de equipe para subissues
• Validação de resolução de usuário
• Validação de filtros de busca

LICENÇA

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENCE para obter detalhes.