pipeyard

Mercado de conectores MCP seleccionados para sectores verticales: Construcción, Finanzas, Salud y Logística, con documentación completa, ejemplos de curl y pruebas en entorno sandbox.

GitHub
4
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Procore

Este proyecto implementa un servidor de Model Context Protocol (MCP) que conecta Claude (y otros clientes compatibles con MCP) a la API de Procore. Expone herramientas para trabajar con:

  • Proyectos
  • RFIs
  • Submittals
  • Documentos
  • Presupuesto y costos

Todas las herramientas devuelven respuestas JSON limpias, validan entradas con zod e incluyen manejo robusto de errores para respuestas 401, 403, 404 y 429 (límite de tasa) de Procore.

Requisitos previos

  • Node.js: v18+ (recomendado)
  • npm: v9+ (incluido con Node.js reciente)
  • Cuenta de desarrollador de Procore con:
    • Un cliente OAuth2 registrado usando el flujo de Client Credentials
    • Acceso a la API para los proyectos/módulos relevantes (RFIs, Submittals, Documentos, Presupuesto, etc.)

Instalación

cd C:\Procore
npm install

Si creaste la carpeta en otra ubicación, ajusta la ruta cd en consecuencia.

Obtención de credenciales de la API de Procore

  • Ve al Portal de Desarrolladores de Procore.
  • Crea un Cliente OAuth usando el tipo de concesión Client Credentials.
  • Anota los siguientes valores:
    • Client ID
    • Client Secret
  • Asegúrate de que el cliente tenga ámbitos de acceso apropiados para:
    • Proyectos
    • RFIs
    • Submittals
    • Documentos
    • Gestión de presupuesto y costos

Usarás estos valores en tu archivo .env.

Configuración de variables de entorno

Crea un archivo .env en la raíz del proyecto (junto a package.json) basado en .env.example:

cp .env.example .env

Luego edita .env:

PROCORE_CLIENT_ID=your_real_client_id
PROCORE_CLIENT_SECRET=your_real_client_secret
PROCORE_BASE_URL=https://api.procore.com
  • PROCORE_CLIENT_ID: Del portal de desarrolladores de Procore.
  • PROCORE_CLIENT_SECRET: Del portal de desarrolladores de Procore.
  • PROCORE_BASE_URL: Normalmente https://api.procore.com (puedes sobrescribirlo para entornos de sandbox/pruebas).

Compilar y ejecutar localmente

Instala las dependencias:

npm install

Ejecuta en modo de desarrollo (TypeScript vía tsx):

npm run dev

Compila TypeScript a dist/:

npm run build

Ejecuta el servidor compilado:

npm start

El servidor MCP usa stdio (entrada/salida estándar), por lo que normalmente es lanzado y gestionado por un cliente MCP como Claude Desktop. Generalmente no lo llamas directamente en una terminal, excepto para depuración.

Herramientas disponibles

Todas las herramientas devuelven JSON. Los argumentos que se muestran a continuación son los argumentos de las herramientas, no llamadas HTTP crudas.

  • Proyectos

    • list_projects
      • Descripción: Lista los proyectos de Procore para el cliente autenticado, opcionalmente filtrados por company_id.
      • Entradas:
        • company_id (opcional, entero): Filtra proyectos por empresa.
    • get_project
      • Descripción: Obtiene los detalles de un solo proyecto por ID.
      • Entradas:
        • id (obligatorio, entero): ID del proyecto.

  • RFIs

    • list_rfis
      • Descripción: Lista los RFIs de un proyecto.
      • Entradas:
        • project_id (obligatorio, entero): ID del proyecto.
    • get_rfi
      • Descripción: Obtiene un solo RFI por ID para un proyecto.
      • Entradas:
        • project_id (obligatorio, entero): ID del proyecto.
        • id (obligatorio, entero): ID del RFI.
    • create_rfi
      • Descripción: Crea un nuevo RFI en un proyecto.
      • Entradas:
        • project_id (obligatorio, entero): ID del proyecto.
        • payload (obligatorio, objeto): Carga útil JSON cruda que coincide con el cuerpo de la API create RFI de Procore.

  • Submittals

    • list_submittals
      • Descripción: Lista los submittals de un proyecto.
      • Entradas:
        • project_id (obligatorio, entero): ID del proyecto.
    • get_submittal
      • Descripción: Obtiene un solo submittal por ID para un proyecto.
      • Entradas:
        • project_id (obligatorio, entero): ID del proyecto.
        • id (obligatorio, entero): ID del submittal.
    • create_submittal
      • Descripción: Crea un nuevo submittal en un proyecto.
      • Entradas:
        • project_id (obligatorio, entero): ID del proyecto.
        • payload (obligatorio, objeto): Carga útil JSON cruda que coincide con el cuerpo de la API create Submittal de Procore.

  • Documentos

    • list_folders
      • Descripción: Lista las carpetas de documentos de un proyecto.
      • Entradas:
        • project_id (obligatorio, entero): ID del proyecto.
    • list_files
      • Descripción: Lista los archivos de documentos de un proyecto.
      • Entradas:
        • project_id (obligatorio, entero): ID del proyecto.

  • Presupuesto

    • list_budget_line_items
      • Descripción: Lista las partidas de presupuesto de un proyecto.
      • Entradas:
        • project_id (obligatorio, entero): ID del proyecto.
    • get_budget_summary
      • Descripción: Obtiene el resumen general del presupuesto de un proyecto.
      • Entradas:
        • project_id (obligatorio, entero): ID del proyecto.

Ejemplos de llamadas a herramientas estilo curl (vía MCP JSON-RPC)

Los servidores MCP hablan JSON-RPC sobre stdio; normalmente no los llamas directamente con curl. Estos ejemplos ilustran la estructura de la carga útil que un cliente como Claude Desktop enviaría.

Reemplaza 123 / 456 etc. con tus IDs reales.

  • Listar proyectos
echo '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {
      "company_id": 123
    }
  }
}' | node dist/index.js
  • Obtener un proyecto
echo '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_project",
    "arguments": {
      "id": 123
    }
  }
}' | node dist/index.js
  • Listar RFIs
echo '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_rfis",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js
  • Crear RFI
echo '{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "create_rfi",
    "arguments": {
      "project_id": 123,
      "payload": {
        "subject": "RFI subject here",
        "question": "Describe the question...",
        "responsible_contractor_id": 456
      }
    }
  }
}' | node dist/index.js
  • Listar submittals
echo '{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "list_submittals",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js
  • Crear submittal
echo '{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "create_submittal",
    "arguments": {
      "project_id": 123,
      "payload": {
        "subject": "Submittal subject",
        "spec_section": "01 30 00",
        "responsible_contractor_id": 456
      }
    }
  }
}' | node dist/index.js
  • Listar carpetas
echo '{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "list_folders",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js
  • Listar archivos
echo '{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js
  • Listar partidas de presupuesto
echo '{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "list_budget_line_items",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js
  • Obtener resumen de presupuesto
echo '{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "get_budget_summary",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js

Comportamiento de manejo de errores

Todas las herramientas incluyen respuestas de error JSON consistentes. Forma típica:

{
  "error": "unauthorized",
  "message": "Procore API returned 401 Unauthorized.",
  "status": 401,
  "statusText": "Unauthorized",
  "url": "/rest/v1.0/projects",
  "method": "get",
  "data": { /* raw Procore response body, if any */ }
}

Estados HTTP manejados:

  • 401: unauthorized
  • 403: forbidden
  • 404: not_found
  • 429: rate_limited
  • Otros 4xx/5xx: procore_api_error
  • Validación / otros errores: tool_error

Cómo conectarse a Claude Desktop (configuración de MCP)

En Claude Desktop, agrega una nueva configuración de servidor MCP en tu claude_desktop_config.json (la ruta puede variar según el sistema operativo).

Ejemplo de entrada:

{
  "mcp_servers": {
    "procore": {
      "command": "node",
      "args": [
        "C:/Procore/procore-mcp-server/dist/index.js"
      ],
      "env": {
        "PROCORE_CLIENT_ID": "your_real_client_id",
        "PROCORE_CLIENT_SECRET": "your_real_client_secret",
        "PROCORE_BASE_URL": "https://api.procore.com"
      }
    }
  }
}
  • command: node (o una ruta explícita a tu binario de Node).
  • args: Ruta al index.js compilado en dist/.
  • env: Puedes:
    • Incluir tus secretos aquí (con precaución), o
    • Omitir env para que Claude Desktop herede las variables de entorno de tu sistema.

Después de guardar la configuración, reinicia Claude Desktop. El servidor MCP procore debería aparecer como un conjunto de herramientas disponible, y las herramientas listadas arriba (list_projects, get_project, list_rfis, etc.) podrán llamarse directamente desde Claude.