pipeyard

Procore MCP Server

This project implements a Model Context Protocol (MCP) server that connects Claude (and other MCP‑aware clients) to the Procore API. It exposes tools for working with:

• Projects
• RFIs
• Submittals
• Documents
• Budget & cost

All tools return clean JSON responses, validate inputs with zod, and include robust error handling for 401, 403, 404, and 429 (rate limit) responses from Procore.

---

Prerequisites

• Node.js: v18+ (recommended)
• npm: v9+ (comes with recent Node.js)
• Procore Developer account with:
  • A registered OAuth2 client using Client Credentials flow
  • API access to the relevant projects/modules (RFIs, Submittals, Documents, Budget, etc.)

---

Installation

cd C:\Procore
npm install

If you created the folder elsewhere, adjust the cd path accordingly.

---

Getting Procore API credentials

• Go to the Procore Developer Portal.
• Create an OAuth Client using the Client Credentials grant type.
• Note the following values:
  • Client ID
  • Client Secret
• Ensure the client has access scopes appropriate for:
  • Projects
  • RFIs
  • Submittals
  • Documents
  • Budget & cost management

You will use these values in your .env file.

---

Environment variable setup

Create a .env file in the project root (next to package.json) based on .env.example:

cp .env.example .env

Then edit .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: From the Procore developer portal.
• PROCORE_CLIENT_SECRET: From the Procore developer portal.
• PROCORE_BASE_URL: Typically https://api.procore.com (you can override for sandbox/test environments).

---

Build and run locally

Install dependencies:

npm install

Run in development mode (TypeScript via tsx):

npm run dev

Build TypeScript to dist/:

npm run build

Run the compiled server:

npm start

The MCP server uses stdio (standard input/output), so it is normally launched and managed by an MCP client such as Claude Desktop. You generally do not call it directly in a terminal except for debugging.

---

Available tools

All tools return JSON. Arguments shown below are the tool arguments, not raw HTTP calls.

• Projects

  • list_projects
    • Description: List Procore projects for the authenticated client, optionally filtered by company_id.
    • Inputs:
      • company_id (optional, integer): Filter projects by company.
  • get_project
    • Description: Get details of a single project by ID.
    • Inputs:
      • id (required, integer): Project ID.

• RFIs

  • list_rfis
    • Description: List RFIs for a project.
    • Inputs:
      • project_id (required, integer): Project ID.
  • get_rfi
    • Description: Get a single RFI by ID for a project.
    • Inputs:
      • project_id (required, integer): Project ID.
      • id (required, integer): RFI ID.
  • create_rfi
    • Description: Create a new RFI in a project.
    • Inputs:
      • project_id (required, integer): Project ID.
      • payload (required, object): Raw JSON payload matching Procore’s create RFI API body.

• Submittals

  • list_submittals
    • Description: List submittals for a project.
    • Inputs:
      • project_id (required, integer): Project ID.
  • get_submittal
    • Description: Get a single submittal by ID for a project.
    • Inputs:
      • project_id (required, integer): Project ID.
      • id (required, integer): Submittal ID.
  • create_submittal
    • Description: Create a new submittal in a project.
    • Inputs:
      • project_id (required, integer): Project ID.
      • payload (required, object): Raw JSON payload matching Procore’s create Submittal API body.

• Documents

  • list_folders
    • Description: List document folders for a project.
    • Inputs:
      • project_id (required, integer): Project ID.
  • list_files
    • Description: List document files for a project.
    • Inputs:
      • project_id (required, integer): Project ID.

• Budget

  • list_budget_line_items
    • Description: List budget line items for a project.
    • Inputs:
      • project_id (required, integer): Project ID.
  • get_budget_summary
    • Description: Get overall budget summary for a project.
    • Inputs:
      • project_id (required, integer): Project ID.

---

Example curl-style tool calls (via MCP JSON-RPC)

MCP servers speak JSON-RPC over stdio; you normally don’t call them directly with curl. These examples illustrate the payload structure a client like Claude Desktop would send.

Replace 123 / 456 etc. with your real IDs.

• List projects

echo '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {
      "company_id": 123
    }
  }
}' | node dist/index.js

• Get a project

echo '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_project",
    "arguments": {
      "id": 123
    }
  }
}' | node dist/index.js

• List RFIs

echo '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_rfis",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js

• Create 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

• List submittals

echo '{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "list_submittals",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js

• Create 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

• List folders

echo '{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "list_folders",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js

• List files

echo '{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js

• List budget line items

echo '{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "list_budget_line_items",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js

• Get budget summary

echo '{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "get_budget_summary",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js

---

Error handling behavior

All tools include consistent JSON error responses. Typical shape:

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

Handled HTTP statuses:

• 401: unauthorized
• 403: forbidden
• 404: not_found
• 429: rate_limited
• Other 4xx/5xx: procore_api_error
• Validation / other errors: tool_error

---

How to connect to Claude Desktop (MCP config)

In Claude Desktop, add a new MCP server configuration in your claude_desktop_config.json (path may vary by OS).

Example entry:

{
  "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 (or an explicit path to your Node binary).
• args: Path to the compiled index.js in dist/.
• env: You can either:
  • Inline your secrets here (be cautious), or
  • Omit env so that Claude Desktop inherits your system environment variables.

After saving the config, restart Claude Desktop. The procore MCP server should appear as an available toolset, and the tools listed above (list_projects, get_project, list_rfis, etc.) will be callable directly from within Claude.