QuickBooks Time

Acesse toda a funcionalidade da API do QuickBooks Time por meio de uma única interface de servidor MCP.

Documentação

Servidor MCP QuickBooks Time (Atualização V2)

Este é um servidor MCP combinado que fornece acesso a todas as funcionalidades da API QuickBooks Time através de uma interface única. Ele combina as funcionalidades de quatro servidores separados:

Ferramentas de JobCode
Ferramentas de Relatórios e Núcleo
Ferramentas de Quadro de Horários
Ferramentas de Usuário

Eu ADORARIA ajuda para melhorar este projeto! Estou feliz em finalmente poder retribuir algo!

Este projeto inteiro foi desenvolvido e publicado usando inteligência artificial (Anthropic, OpenAI, Llama/META), pois pessoalmente não consigo escrever muito código sem assistência. Embora todos os esforços tenham sido feitos para garantir qualidade e funcionalidade, pode haver imperfeições ou áreas para melhoria. Agradeço qualquer feedback, correção ou sugestão da comunidade.

Instale as dependências:

pip install -r requirements.txt

Crie um arquivo .env com seu token de acesso QuickBooks Time:

QB_TIME_ACCESS_TOKEN=your_access_token_here
NODE_ENV=development

Configuração do Claude Desktop

Para usar este servidor com o Claude Desktop, você precisará configurá-lo nas configurações do Claude Desktop. Aqui está um exemplo de configuração:

{
  "globalShortcut": "Ctrl+Q",
  "mcpServers": {
    "qb-time-tools": {
      "command": "python",
      "args": [
        "./qb-time-mcp-server/main.py"
      ],
      "env": {
        "QB_TIME_ACCESS_TOKEN": "your_quickbooks_time_access_token_here"
      }
    }
  }
}

Ferramentas Disponíveis

Ferramentas de JobCode

get_jobcodes: Obter jobcodes com opções avançadas de filtro
- Filtros Básicos:
  - ids: (matriz de números, opcional) Lista separada por vírgulas de IDs de jobcode
  - name: (string, opcional) Filtrar por nome do jobcode, suporta correspondência com curinga (*) desde o início da string
  - active: (string, opcional) Filtrar por status: "yes", "no", "both" (padrão: "yes")
- Filtros de Tipo e Hierarquia:
  - type: (string, opcional) Filtrar por tipo: "regular", "pto", "paid_break", "unpaid_break", "all" (padrão: "regular")
  - parent_ids: (matriz de números, opcional) Filtrar por IDs de jobcode pai. Valores especiais: 0 (somente nível superior), -1 (todos os níveis)
- Filtros Adicionais:
  - customfields: (booleano, opcional) Incluir campos personalizados na resposta
  - modified_before: (string, opcional) Filtrar por data de modificação (formato ISO 8601)
  - modified_since: (string, opcional) Filtrar por data de modificação (formato ISO 8601)
  - page: (número) Número da página para paginação
  - limit: (número) Resultados por página (máx. 200)
get_jobcode: Obter um jobcode específico por ID
- Parâmetros Obrigatórios:
  - id: (número) O ID do jobcode a ser recuperado
get_jobcode_hierarchy: Obter estrutura completa da hierarquia de jobcodes
- Parâmetros:
  - parent_ids: (matriz de números, opcional) Filtrar por IDs pai. Valores: 0 (nível superior), -1 (todos) ou IDs específicos
  - active: (string, opcional) Filtrar por status: "yes", "no", "both" (padrão: "yes")
  - type: (string, opcional) Filtrar por tipo: "regular", "pto", "paid_break", "unpaid_break", "all" (padrão: "regular")
  - customfields: (booleano, opcional) Incluir campos personalizados na resposta

Ferramentas de Quadro de Horários

get_timesheets: Obter quadros de horários com filtragem
- Parâmetros Obrigatórios (pelo menos um):
  - ids: (matriz de números) Lista separada por vírgulas de IDs de quadro de horários
  - start_date: (string) Retorna quadros de horários nesta data ou após ela (AAAA-MM-DD)
  - modified_before: (string) Retorna quadros de horários modificados antes deste horário (ISO 8601)
  - modified_since: (string) Retorna quadros de horários modificados desde este horário (ISO 8601)
- Parâmetros Opcionais:
  - end_date: (string) Retorna quadros de horários nesta data ou antes dela (AAAA-MM-DD)
  - user_ids: (matriz de números) Filtrar por IDs de usuário específicos
  - group_ids: (matriz de números) Filtrar por IDs de grupo específicos
  - jobcode_ids: (matriz de números) Filtrar por IDs de jobcode específicos (inclui filhos)
  - payroll_ids: (matriz de números) Filtrar por IDs de folha de pagamento específicos
  - on_the_clock: (string) Filtrar por status de trabalho atual: "yes", "no", "both" (padrão: "no")
  - jobcode_type: (string) Filtrar por tipo: "regular", "pto", "paid_break", "unpaid_break", "all" (padrão: "all")
  - page: (número) Número da página
  - limit: (número) Resultados por página
get_timesheet: Obter um quadro de horários específico por ID
- Parâmetros Obrigatórios:
  - id: (número) O ID do quadro de horários a ser recuperado
get_current_timesheets: Obter quadros de horários atualmente ativos
- Parâmetros Obrigatórios:
  - on_the_clock: (string) Deve ser definido como "yes"
- Parâmetros Opcionais:
  - user_ids: (matriz de números) Filtrar quadros de horários ativos para usuários específicos
  - group_ids: (matriz de números) Filtrar quadros de horários ativos para usuários em grupos específicos
  - jobcode_ids: (matriz de números) Filtrar quadros de horários ativos para jobcodes específicos
  - supplemental_data: (string) Incluir dados suplementares: "yes", "no" (padrão: "yes")

Ferramentas de Usuário

get_users: Obter todos os usuários com filtragem
- Filtros de Identificação de Usuário:
  - ids: (matriz de números, opcional) Filtrar por IDs de usuário específicos
  - not_ids: (matriz de números, opcional) Excluir IDs de usuário específicos
  - employee_numbers: (matriz de números, opcional) Filtrar por números de funcionário
  - usernames: (matriz de strings, opcional) Filtrar por nomes de usuário específicos
- Filtros de Grupo:
  - group_ids: (matriz de números, opcional) Filtrar por associação a grupo
  - not_group_ids: (matriz de números, opcional) Excluir usuários de grupos específicos
- Filtros de Status e Identificação:
  - payroll_ids: (matriz de strings, opcional) Filtrar por números de identificação de folha de pagamento
  - active: (string, opcional) Filtrar por status: "yes", "no", "both" (padrão: "yes")
- Filtros de Nome:
  - first_name: (string, opcional) Filtrar por primeiro nome (suporta curingas *)
  - last_name: (string, opcional) Filtrar por sobrenome (suporta curingas *)
- Filtros Baseados em Tempo:
  - modified_before: (string, opcional) Filtrar por data de modificação (ISO 8601)
  - modified_since: (string, opcional) Filtrar por data de modificação (ISO 8601)
- Paginação:
  - page: (número, opcional) Número da página (padrão: 1)
  - per_page: (número, opcional) Resultados por página (padrão: 50, máx.: 50)
get_user: Obter um usuário específico por ID
- Parâmetros Obrigatórios:
  - id: (número) O ID do usuário a ser recuperado
get_current_user: Obter usuário atualmente autenticado
- Nenhum parâmetro necessário
- Retorna informações detalhadas do usuário, incluindo:
  - Informações básicas do perfil
  - Detalhes da empresa
  - Saldos de PTO
  - Permissões
  - Campos personalizados
get_groups: Obter todos os grupos do QuickBooks Time
- Parâmetros Opcionais:
  - ids: (matriz de números) Filtrar por IDs de grupo específicos
  - active: (string) Filtrar por status: "yes", "no", "both" (padrão: "yes")
  - manager_ids: (matriz de números) Filtrar grupos por IDs de usuário gerente
  - supplemental_data: (string) Incluir dados suplementares: "yes", "no" (padrão: "yes")
- Retorna informações do grupo, incluindo:
  - Detalhes básicos do grupo
  - Atribuições de gerente
  - Configurações de quadro de horários
  - Configurações de entrada de tempo
  - Configurações de intervalo

Ferramentas de Gerenciamento de Projetos

get_projects: Obter projetos com filtragem
- Parâmetros Opcionais:
  - ids: (matriz de números) Filtrar por IDs de projeto específicos
  - active: (string) Filtrar por status: "yes", "no", "both" (padrão: "yes")
  - client_id: (número) Filtrar por ID de cliente
  - jobcode_id: (número) Filtrar por ID de jobcode associado
  - modified_before: (string) Filtrar por data de modificação (ISO 8601)
  - modified_since: (string) Filtrar por data de modificação (ISO 8601)
  - page: (número) Número da página (padrão: 1)
  - per_page: (número) Resultados por página (padrão: 50, máx.: 50)
- Retorna informações do projeto, incluindo:
  - Detalhes básicos do projeto
  - Associações de cliente e jobcode
  - Informações de orçamento
  - Datas e status
  - Campos personalizados
get_project_activities: Obter registros de atividade do projeto
- Parâmetros Opcionais:
  - project_ids: (matriz de números) Filtrar atividades para projetos específicos
  - user_ids: (matriz de números) Filtrar atividades por usuários específicos
  - activity_types: (matriz de strings) Filtrar por tipos de atividade: "status_change", "note_added", "budget_change", "date_change", "custom_field_change"
  - modified_before: (string) Filtrar por data de modificação (ISO 8601)
  - modified_since: (string) Filtrar por data de modificação (ISO 8601)
  - page: (número) Número da página (padrão: 1)
  - per_page: (número) Resultados por página (padrão: 50, máx.: 50)
- Retorna informações de atividade, incluindo:
  - Tipo de atividade e detalhes
  - Usuário que fez a alteração
  - Valores antigos e novos
  - Carimbos de data/hora

Ferramentas de Relatórios

get_current_totals: Obter instantâneo de totais atuais, incluindo totais de turno e diários
- Parâmetros Opcionais:
  - user_ids: (matriz de números) Filtrar totais para usuários específicos
  - group_ids: (matriz de números) Filtrar totais para usuários em grupos específicos
  - jobcode_ids: (matriz de números) Filtrar totais para jobcodes específicos
  - customfield_query: (string) Filtrar por valores de campos personalizados no formato: <customfield_id>||
- Retorna:
  - Totais em tempo real para entradas de tempo ativas
  - Duração e horários de início
  - Informações de jobcode e usuário associados
  - Valores de campos personalizados
get_payroll: Obter relatório de folha de pagamento
- Parâmetros Obrigatórios:
  - start_date: (string) Início do período de pagamento (AAAA-MM-DD)
  - end_date: (string) Fim do período de pagamento (AAAA-MM-DD)
- Parâmetros Opcionais:
  - user_ids: (matriz de números) Filtrar folha de pagamento para usuários específicos
  - group_ids: (matriz de números) Filtrar folha de pagamento para usuários em grupos específicos
  - include_zero_time: (booleano) Incluir usuários sem entradas de tempo (padrão: false)
- Retorna:
  - Tempo total por tipo (regular, horas extras, tempo duplo, PTO)
  - Discriminações diárias por usuário
  - Contagens de quadros de horários
get_payroll_by_jobcode: Obter relatório de folha de pagamento agrupado por jobcode
- Parâmetros Obrigatórios:
  - start_date: (string) Início do período de pagamento (AAAA-MM-DD)
  - end_date: (string) Fim do período de pagamento (AAAA-MM-DD)
- Parâmetros Opcionais:
  - user_ids: (matriz de números) Filtrar folha de pagamento para usuários específicos
  - group_ids: (matriz de números) Filtrar folha de pagamento para usuários em grupos específicos
  - jobcode_ids: (matriz de números) Filtrar folha de pagamento para jobcodes específicos
  - jobcode_type: (string) Filtrar por tipo: "regular", "pto", "paid_break", "unpaid_break"
  - include_zero_time: (booleano) Incluir jobcodes sem entradas de tempo (padrão: false)
- Retorna:
  - Totais de tempo por jobcode
  - Discriminações por usuário dentro de cada jobcode
  - Totais diários por jobcode
get_project_report: Obter relatório detalhado de projeto com entradas de tempo
- Parâmetros Obrigatórios:
  - start_date: (string) Data de início no formato AAAA-MM-DD
  - end_date: (string) Data de fim no formato AAAA-MM-DD
- Parâmetros Opcionais:
  - user_ids: (matriz de números) Filtrar entradas de tempo por usuários específicos
  - group_ids: (matriz de números) Filtrar entradas de tempo por grupos específicos
  - jobcode_ids: (matriz de números) Filtrar entradas de tempo por jobcodes específicos
  - jobcode_type: (string) Filtrar por tipo: "regular", "pto", "unpaid_break", "paid_break", "all" (padrão: "all")
  - customfielditems: (objeto) Filtrar por valores de campos personalizados no formato: {"customfield_id": ["value1", "value2"]}
- Retorna:
  - Totais de tempo do projeto
  - Discriminações por usuário e grupo
  - Entradas de tempo filtradas com base nos critérios

Ferramentas Adicionais

get_custom_fields: Obter campos de rastreamento personalizados configurados nos cartões de ponto
- Parâmetros:
  - ids: (array de números) Filtrar por IDs específicos de campos personalizados
  - active: (string) Filtrar por status: "yes", "no", "both"
  - applies_to: (string) Filtrar por tipo de aplicação: "timesheet", "jobcode", "user"
  - value_type: (string) Filtrar por tipo de valor: "managed-list", "free-form"
  - page: (número) Número da página
  - limit: (número) Resultados por página
get_last_modified: Obter carimbos de data/hora da última modificação para objetos
- Parâmetros:
  - types: (array de strings) Tipos de objetos a verificar (ex.: ["timesheets", "jobcodes", "users"])
get_notifications: Obter notificações
- Parâmetros:
  - page: (número) Número da página
  - limit: (número) Resultados por página
get_managed_clients: Obter clientes gerenciados
- Parâmetros:
  - page: (número) Número da página
  - limit: (número) Resultados por página

Executando o Servidor

python main.py

O servidor iniciará e escutará por solicitações JSON-RPC em stdin/stdout.

Licença

Licença MIT - Consulte o arquivo LICENSE para detalhes

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Dado que este projeto foi desenvolvido com assistência de IA, a contribuição da comunidade é especialmente valiosa para melhorar e manter o código.

Suporte

Para problemas e solicitações de recursos, use a página de issues do GitHub ou entre em contato diretamente em github.com/aallsbury.