qb-time-mcp-server

Servidor MCP de tiempo de QuickBooks (actualización V2)

Este es un servidor MCP combinado que proporciona acceso a todas las funciones de la API de QuickBooks Time a través de una única interfaz. Combina la funcionalidad de cuatro servidores independientes:

1. Herramientas de JobCode
2. Informes y herramientas principales
3. Herramientas de hoja de horas
4. Herramientas de usuario

¡Me encantaría ayudar a mejorar este proyecto! ¡Me alegra poder finalmente contribuir!

Todo este proyecto se desarrolló y publicó utilizando inteligencia artificial (Anthropic, OpenAI, Llama/META), ya que personalmente no puedo escribir mucho código sin ayuda. Si bien se ha hecho todo lo posible para garantizar la calidad y la funcionalidad, puede haber imperfecciones o áreas de mejora. Agradezco cualquier comentario, corrección o sugerencia de la comunidad.

1. Instalar dependencias:

2. Cree un archivo .env con su token de acceso de QuickBooks Time:

Configuración del escritorio de Claude

Para usar este servidor con Claude Desktop, deberá configurarlo en la configuración de Claude Desktop. A continuación, se muestra un ejemplo de configuración:

Herramientas disponibles

Herramientas de JobCode

• get_jobcodes : Obtenga códigos de trabajo con opciones de filtrado avanzadas
  • Filtros básicos:
    • ids : (matriz de números, opcional) Lista separada por comas de identificaciones de códigos de trabajo
    • name : (cadena, opcional) Filtrar por nombre de código de trabajo, admite coincidencia con comodín (*) desde el inicio de la cadena
    • active : (cadena, opcional) Filtrar por estado: "sí", "no", "ambos" (predeterminado: "sí")
  • Filtros de tipo y jerarquía:
    • type : (cadena, opcional) Filtrar por tipo: "regular", "pto", "paid_break", "unpaid_break", "all" (predeterminado: "regular")
    • parent_ids : (matriz de números, opcional) Filtrar por ID de código de trabajo principal. Valores especiales: 0 (solo nivel superior), -1 (todos los niveles)
  • Filtros adicionales:
    • customfields : (booleano, opcional) Incluir campos personalizados en la respuesta
    • modified_before : (cadena, opcional) Filtrar por fecha de modificación (formato ISO 8601)
    • modified_since : (cadena, opcional) Filtrar por fecha de modificación (formato ISO 8601)
    • page : (número) Número de página para paginación
    • limit : (número) Resultados por página (máximo 200)
• get_jobcode : Obtener un código de trabajo específico por ID
  • Parámetros requeridos:
    • id : (número) El ID del código de trabajo a recuperar
• get_jobcode_hierarchy : Obtener la estructura jerárquica completa del código de trabajo
  • Parámetros:
    • parent_ids : (matriz de números, opcional) Filtrar por ID de padre. Valores: 0 (nivel superior), -1 (todos) o ID específicos.
    • active : (cadena, opcional) Filtrar por estado: "sí", "no", "ambos" (predeterminado: "sí")
    • type : (cadena, opcional) Filtrar por tipo: "regular", "pto", "paid_break", "unpaid_break", "all" (predeterminado: "regular")
    • customfields : (booleano, opcional) Incluir campos personalizados en la respuesta

Herramientas de hoja de horas

• get_timesheets : Obtener hojas de horas con filtrado
  • Parámetros obligatorios (al menos uno):
    • ids : (matriz de números) Lista separada por comas de identificaciones de hojas de horas
    • start_date : (cadena) Devuelve las hojas de horas en o después de esta fecha (AAAA-MM-DD)
    • modified_before : (cadena) Devuelve las hojas de horas modificadas antes de este momento (ISO 8601)
    • modified_since : (cadena) Devuelve las hojas de horas modificadas desde este momento (ISO 8601)
  • Parámetros opcionales:
    • end_date : (cadena) Devuelve las hojas de horas en o antes de esta fecha (AAAA-MM-DD)
    • user_ids : (matriz de números) Filtrar por ID de usuario específicos
    • group_ids : (matriz de números) Filtrar por ID de grupo específicos
    • jobcode_ids : (matriz de números) Filtrar por ID de código de trabajo específicos (incluye elementos secundarios)
    • payroll_ids : (matriz de números) Filtrar por ID de nómina específicos
    • on_the_clock : (cadena) Filtrar por estado de funcionamiento actual: "sí", "no", "ambos" (predeterminado: "no")
    • jobcode_type : (cadena) Filtrar por tipo: "regular", "pto", "paid_break", "unpaid_break", "all" (predeterminado: "all")
    • page : (número) Número de página
    • limit : (número) Resultados por página
• get_timesheet : Obtener una hoja de horas específica por ID
  • Parámetros requeridos:
    • id : (número) El ID de la hoja de horas a recuperar
• get_current_timesheets : Obtener las hojas de horas activas actualmente
  • Parámetros requeridos:
    • on_the_clock : (cadena) Debe establecerse en "sí"
  • Parámetros opcionales:
    • user_ids : (matriz de números) Filtrar hojas de horas activas para usuarios específicos
    • group_ids : (matriz de números) Filtrar planillas de horas activas para usuarios en grupos específicos
    • jobcode_ids : (matriz de números) Filtrar hojas de horas activas para códigos de trabajo específicos
    • supplemental_data : (cadena) Incluye datos suplementarios: "sí", "no" (predeterminado: "sí")

Herramientas de usuario

• get_users : Obtener todos los usuarios con filtrado
  • Filtros de identificación de usuario:
    • ids : (matriz de números, opcional) Filtrar por ID de usuario específicos
    • not_ids : (matriz de números, opcional) Excluye identificaciones de usuario específicas
    • employee_numbers : (matriz de números, opcional) Filtrar por números de empleados
    • usernames : (matriz de cadenas, opcional) Filtrar por nombres de usuario específicos
  • Filtros de grupo:
    • group_ids : (matriz de números, opcional) Filtrar por membresía de grupo
    • not_group_ids : (matriz de números, opcional) Excluye usuarios de grupos específicos
  • Filtros de estado e identificación:
    • payroll_ids : (matriz de cadenas, opcional) Filtrar por números de identificación de nómina
    • active : (cadena, opcional) Filtrar por estado: "sí", "no", "ambos" (predeterminado: "sí")
  • Filtros de nombre:
    • first_name : (cadena, opcional) Filtrar por nombre (admite comodines *)
    • last_name : (cadena, opcional) Filtrar por apellido (admite comodines *)
  • Filtros basados en el tiempo:
    • modified_before : (cadena, opcional) Filtrar por fecha de modificación (ISO 8601)
    • modified_since : (cadena, opcional) Filtrar por fecha de modificación (ISO 8601)
  • Paginación:
    • page : (número, opcional) Número de página (predeterminado: 1)
    • per_page : (número, opcional) Resultados por página (predeterminado: 50, máximo: 50)
• get_user : Obtener un usuario específico por ID
  • Parámetros requeridos:
    • id : (número) El ID del usuario a recuperar
• get_current_user : Obtener el usuario autenticado actualmente
  • No se requieren parámetros
  • Devuelve información detallada del usuario, que incluye:
    • Información básica del perfil
    • Datos de la empresa
    • Saldos de PTO
    • Permisos
    • Campos personalizados
• get_groups : Obtener todos los grupos de QuickBooks Time
  • Parámetros opcionales:
    • ids : (matriz de números) Filtrar por ID de grupo específicos
    • active : (cadena) Filtrar por estado: "sí", "no", "ambos" (predeterminado: "sí")
    • manager_ids : (matriz de números) Filtra grupos por ID de usuario de administrador
    • supplemental_data : (cadena) Incluye datos suplementarios: "sí", "no" (predeterminado: "sí")
  • Devuelve información del grupo que incluye:
    • Detalles básicos del grupo
    • Asignaciones de gerente
    • Configuración de la hoja de horas
    • Configuración de entrada de tiempo
    • Configuración de descanso

Herramientas de gestión de proyectos

• get_projects : Obtener proyectos con filtrado
  • Parámetros opcionales:
    • ids : (matriz de números) Filtrar por ID de proyecto específicos
    • active : (cadena) Filtrar por estado: "sí", "no", "ambos" (predeterminado: "sí")
    • client_id : (número) Filtrar por ID de cliente
    • jobcode_id : (número) Filtrar por ID de código de trabajo asociado
    • modified_before : (cadena) Filtrar por fecha de modificación (ISO 8601)
    • modified_since : (cadena) Filtrar por fecha de modificación (ISO 8601)
    • page : (número) Número de página (predeterminado: 1)
    • per_page : (número) Resultados por página (predeterminado: 50, máximo: 50)
  • Devuelve información del proyecto, incluyendo:
    • Detalles básicos del proyecto
    • Asociaciones de clientes y códigos de trabajo
    • Información presupuestaria
    • Fechas y estado
    • Campos personalizados
• get_project_activities : Obtener registros de actividad del proyecto
  • Parámetros opcionales:
    • project_ids : (matriz de números) Filtrar actividades para proyectos específicos
    • user_ids : (matriz de números) Filtrar actividades por usuarios específicos
    • activity_types : (matriz de cadenas) Filtrar por tipos de actividad: "cambio_de_estado", "nota_añadida", "cambio_de_presupuesto", "cambio_de_fecha", "cambio_de_campo_personalizado"
    • modified_before : (cadena) Filtrar por fecha de modificación (ISO 8601)
    • modified_since : (cadena) Filtrar por fecha de modificación (ISO 8601)
    • page : (número) Número de página (predeterminado: 1)
    • per_page : (número) Resultados por página (predeterminado: 50, máximo: 50)
  • Devuelve información de la actividad, incluyendo:
    • Tipo de actividad y detalles
    • Usuario que realizó el cambio
    • Valores antiguos y nuevos
    • Marcas de tiempo

Herramientas de informes

• get_current_totals : Obtener una instantánea de los totales actuales, incluidos los totales de turno y día
  • Parámetros opcionales:
    • user_ids : (matriz de números) Filtrar totales para usuarios específicos
    • group_ids : (matriz de números) Filtrar totales para usuarios en grupos específicos
    • jobcode_ids : (matriz de números) Filtrar totales para códigos de trabajo específicos
    • customfield_query : (cadena) Filtrar por valores de campos personalizados en formato: <customfield_id>||
  • Devoluciones:
    • Totales en tiempo real para entradas de tiempo activas
    • Duración y horas de inicio
    • Código de trabajo asociado e información de usuario
    • Valores de campos personalizados
• get_payroll : Obtener informe de nómina
  • Parámetros requeridos:
    • start_date : (cadena) Inicio del período de pago (AAAA-MM-DD)
    • end_date : (cadena) Fin del período de pago (AAAA-MM-DD)
  • Parámetros opcionales:
    • user_ids : (matriz de números) Filtrar la nómina para usuarios específicos
    • group_ids : (matriz de números) Filtrar la nómina para usuarios en grupos específicos
    • include_zero_time : (booleano) Incluye usuarios sin entradas de tiempo (valor predeterminado: falso)
  • Devoluciones:
    • Tiempo total por tipo (regular, horas extra, tiempo doble, PTO)
    • Desgloses diarios por usuario
    • Recuentos de la hoja de horas
• get_payroll_by_jobcode : Obtener el informe de nómina agrupado por código de trabajo
  • Parámetros requeridos:
    • start_date : (cadena) Inicio del período de pago (AAAA-MM-DD)
    • end_date : (cadena) Fin del período de pago (AAAA-MM-DD)
  • Parámetros opcionales:
    • user_ids : (matriz de números) Filtrar la nómina para usuarios específicos
    • group_ids : (matriz de números) Filtrar la nómina para usuarios en grupos específicos
    • jobcode_ids : (matriz de números) Filtrar la nómina para códigos de trabajo específicos
    • jobcode_type : (cadena) Filtrar por tipo: "regular", "pto", "receso remunerado", "receso no remunerado"
    • include_zero_time : (booleano) Incluye códigos de trabajo sin entradas de tiempo (valor predeterminado: falso)
  • Devoluciones:
    • Totales de tiempo por código de trabajo
    • Desgloses por usuario dentro de cada código de trabajo
    • Totales diarios por código de trabajo
• get_project_report : Obtenga un informe detallado del proyecto con entradas de tiempo
  • Parámetros requeridos:
    • start_date : (cadena) Fecha de inicio en formato AAAA-MM-DD
    • end_date : (cadena) Fecha de finalización en formato AAAA-MM-DD
  • Parámetros opcionales:
    • user_ids : (matriz de números) Filtrar entradas de tiempo por usuarios específicos
    • group_ids : (matriz de números) Filtrar entradas de tiempo por grupos específicos
    • jobcode_ids : (matriz de números) Filtrar entradas de tiempo por códigos de trabajo específicos
    • jobcode_type : (cadena) Filtrar por tipo: "regular", "pto", "unpaid_break", "paid_break", "all" (predeterminado: "all")
    • customfielditems : (objeto) Filtrar por valores de campos personalizados en formato: {"customfield_id": ["valor1", "valor2"]}
  • Devoluciones:
    • Totales de tiempo del proyecto
    • Desgloses por usuario y grupo
    • Entradas de tiempo filtradas según criterios

Herramientas adicionales

• get_custom_fields : Obtener campos de seguimiento personalizados configurados en las tarjetas de tiempo
  • Parámetros:
    • ids : (matriz de números) Filtrar por ID de campos personalizados específicos
    • active : (cadena) Filtrar por estado: "sí", "no", "ambos"
    • applies_to : (cadena) Filtrar por tipo de aplicación: "hoja de horas", "código de trabajo", "usuario"
    • value_type : (cadena) Filtrar por tipo de valor: "lista administrada", "formato libre"
    • page : (número) Número de página
    • limit : (número) Resultados por página
• get_last_modified : Obtener las marcas de tiempo de la última modificación de los objetos
  • Parámetros:
    • types : (matriz de cadenas) Tipos de objetos a comprobar (por ejemplo, ["hojas de tiempo", "códigos de trabajo", "usuarios"])
• get_notifications : Recibir notificaciones
  • Parámetros:
    • page : (número) Número de página
    • limit : (número) Resultados por página
• get_managed_clients : Obtener clientes administrados
  • Parámetros:
    • page : (número) Número de página
    • limit : (número) Resultados por página

Ejecución del servidor

El servidor se iniciará y escuchará las solicitudes JSON-RPC en stdin/stdout.

Licencia

Licencia MIT: consulte el archivo LICENCIA para obtener más detalles

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios. Dado que este proyecto se desarrolló con la ayuda de IA, las aportaciones de la comunidad son especialmente valiosas para mejorar y mantener el código base.

Apoyo

Para problemas y solicitudes de funciones, utilice la página de problemas de GitHub o contácteme directamente en github.com/aallsbury.