QuickBooks Time

Acceda a toda la funcionalidad de la API de QuickBooks Time a través de una única interfaz de servidor MCP.

GitHub
11
Prueba este MCPPatrocinado

Documentación

Servidor MCP de QuickBooks Time (Actualización V2)

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

  1. Herramientas de JobCode
  2. Herramientas de Informes y Núcleo
  3. Herramientas de Hojas de Tiempo
  4. Herramientas de Usuario

¡Me ENCANTARÍA recibir ayuda para mejorar este proyecto! ¡Me alegra poder finalmente aportar algo!

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

  1. Instalar dependencias:
pip install -r requirements.txt
  1. Crear un archivo .env con tu token de acceso de QuickBooks Time:
QB_TIME_ACCESS_TOKEN=your_access_token_here
NODE_ENV=development

Configuración de Claude Desktop

Para usar este servidor con Claude Desktop, deberás configurarlo en la configuración de Claude Desktop. Aquí tienes un ejemplo de configuración:

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

Herramientas Disponibles

Herramientas de JobCode

  • get_jobcodes: Obtener jobcodes con opciones de filtrado avanzadas

    • Filtros Básicos:
      • ids: (matriz de números, opcional) Lista separada por comas de IDs de jobcode
      • name: (cadena, opcional) Filtrar por nombre de jobcode, admite coincidencia con comodín (*) desde el inicio de la cadena
      • active: (cadena, opcional) Filtrar por estado: "yes", "no", "both" (predeterminado: "yes")
    • 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 IDs de jobcode padre. 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áx. 200)

  • get_jobcode: Obtener un jobcode específico por ID

    • Parámetros Requeridos:
      • id: (número) El ID del jobcode a recuperar

  • get_jobcode_hierarchy: Obtener la estructura completa de jerarquía de jobcodes

    • Parámetros:
      • parent_ids: (matriz de números, opcional) Filtrar por IDs de padre. Valores: 0 (nivel superior), -1 (todos), o IDs específicos
      • active: (cadena, opcional) Filtrar por estado: "yes", "no", "both" (predeterminado: "yes")
      • 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 Hojas de Tiempo

  • get_timesheets: Obtener hojas de tiempo con filtrado

    • Parámetros Requeridos (al menos uno):
      • ids: (matriz de números) Lista separada por comas de IDs de hojas de tiempo
      • start_date: (cadena) Devuelve hojas de tiempo en o después de esta fecha (AAAA-MM-DD)
      • modified_before: (cadena) Devuelve hojas de tiempo modificadas antes de esta hora (ISO 8601)
      • modified_since: (cadena) Devuelve hojas de tiempo modificadas desde esta hora (ISO 8601)
    • Parámetros Opcionales:
      • end_date: (cadena) Devuelve hojas de tiempo en o antes de esta fecha (AAAA-MM-DD)
      • user_ids: (matriz de números) Filtrar por IDs de usuario 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 (incluye hijos)
      • payroll_ids: (matriz de números) Filtrar por IDs de nómina específicos
      • on_the_clock: (cadena) Filtrar por estado de trabajo actual: "yes", "no", "both" (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 tiempo específica por ID

    • Parámetros Requeridos:
      • id: (número) El ID de la hoja de tiempo a recuperar

  • get_current_timesheets: Obtener hojas de tiempo actualmente activas

    • Parámetros Requeridos:
      • on_the_clock: (cadena) Debe establecerse en "yes"
    • Parámetros Opcionales:
      • user_ids: (matriz de números) Filtrar hojas de tiempo activas para usuarios específicos
      • group_ids: (matriz de números) Filtrar hojas de tiempo activas para usuarios en grupos específicos
      • jobcode_ids: (matriz de números) Filtrar hojas de tiempo activas para jobcodes específicos
      • supplemental_data: (cadena) Incluir datos complementarios: "yes", "no" (predeterminado: "yes")

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 IDs de usuario específicos
      • not_ids: (matriz de números, opcional) Excluir IDs de usuario específicos
      • employee_numbers: (matriz de números, opcional) Filtrar por números de empleado
      • 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) Excluir 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: "yes", "no", "both" (predeterminado: "yes")
    • Filtros de Nombre:
      • first_name: (cadena, opcional) Filtrar por nombre (admite comodines *)
      • last_name: (cadena, opcional) Filtrar por apellido (admite comodines *)
    • Filtros Basados en 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áx.: 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 actualmente autenticado

    • No se requieren parámetros
    • Devuelve información detallada del usuario que incluye:
      • Información básica del perfil
      • Detalles 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 IDs de grupo específicos
      • active: (cadena) Filtrar por estado: "yes", "no", "both" (predeterminado: "yes")
      • manager_ids: (matriz de números) Filtrar grupos por IDs de usuario gerente
      • supplemental_data: (cadena) Incluir datos complementarios: "yes", "no" (predeterminado: "yes")
    • Devuelve información del grupo que incluye:
      • Detalles básicos del grupo
      • Asignaciones de gerentes
      • Configuración de hojas de tiempo
      • Configuración de entrada de tiempo
      • Configuración de descansos

Herramientas de Gestión de Proyectos

  • get_projects: Obtener proyectos con filtrado

    • Parámetros Opcionales:
      • ids: (matriz de números) Filtrar por IDs de proyecto específicos
      • active: (cadena) Filtrar por estado: "yes", "no", "both" (predeterminado: "yes")
      • client_id: (número) Filtrar por ID de cliente
      • jobcode_id: (número) Filtrar por ID de jobcode 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áx.: 50)
    • Devuelve información del proyecto que incluye:
      • Detalles básicos del proyecto
      • Asociaciones de cliente y jobcode
      • Información de presupuesto
      • 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 a 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: "status_change", "note_added", "budget_change", "date_change", "custom_field_change"
      • 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áx.: 50)
    • Devuelve información de actividad que incluye:
      • Tipo de actividad y detalles
      • Usuario que realizó el cambio
      • Valores antiguos y nuevos
      • Marcas de tiempo

Herramientas de Informes

  • get_current_totals: Obtener instantánea de totales actuales, incluidos totales de turno y diarios

    • Parámetros Opcionales:
      • user_ids: (matriz de números) Filtrar totales a 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 jobcodes específicos
      • customfield_query: (cadena) Filtrar por valores de campos personalizados en formato: <customfield_id>||
    • Devuelve:
      • Totales en tiempo real para entradas de tiempo activas
      • Duración y horas de inicio
      • Información de jobcode y usuario asociados
      • 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 nómina para usuarios específicos
      • group_ids: (matriz de números) Filtrar nómina para usuarios en grupos específicos
      • include_zero_time: (booleano) Incluir usuarios sin entradas de tiempo (predeterminado: false)
    • Devuelve:
      • Tiempo total por tipo (regular, horas extra, doble tiempo, PTO)
      • Desgloses diarios por usuario
      • Conteos de hojas de tiempo

  • get_payroll_by_jobcode: Obtener informe de nómina agrupado por jobcode

    • 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 nómina para usuarios específicos
      • group_ids: (matriz de números) Filtrar nómina para usuarios en grupos específicos
      • jobcode_ids: (matriz de números) Filtrar nómina para jobcodes específicos
      • jobcode_type: (cadena) Filtrar por tipo: "regular", "pto", "paid_break", "unpaid_break"
      • include_zero_time: (booleano) Incluir jobcodes sin entradas de tiempo (predeterminado: false)
    • Devuelve:
      • Totales de tiempo por jobcode
      • Desgloses por usuario dentro de cada jobcode
      • Totales diarios por jobcode

  • get_project_report: Obtener informe detallado de proyecto con entradas de tiempo

    • Parámetros Requeridos:
      • start_date: (cadena) Fecha de inicio en formato AAAA-MM-DD
      • end_date: (cadena) Fecha de fin 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 jobcodes 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": ["value1", "value2"]}
    • Devuelve:
      • 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 IDs de campos personalizados específicos
      • active: (cadena) Filtrar por estado: "yes", "no", "both"
      • applies_to: (cadena) Filtrar por tipo de aplicación: "timesheet", "jobcode", "user"
      • value_type: (cadena) Filtrar por tipo de valor: "managed-list", "free-form"
      • page: (número) Número de página
      • limit: (número) Resultados por página

  • get_last_modified: Obtener marcas de tiempo de última modificación para objetos

    • Parámetros:
      • types: (matriz de cadenas) Tipos de objetos a verificar (p. ej., ["timesheets", "jobcodes", "users"])

  • get_notifications: Obtener notificaciones

    • Parámetros:
      • page: (número) Número de página
      • limit: (número) Resultados por página

  • get_managed_clients: Obtener clientes gestionados

    • Parámetros:
      • page: (número) Número de página
      • limit: (número) Resultados por página

Ejecutar el Servidor

python main.py

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

Licencia

Licencia MIT - Consulte el archivo LICENSE para más detalles

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request). Dado que este proyecto fue desarrollado con asistencia de IA, la aportación de la comunidad es especialmente valiosa para mejorar y mantener el código base.

Soporte

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