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```bash
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`:```bash
cp .env.example .env
Then edit .env:```bash
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:```bash
npm install
Run in development mode (TypeScript via tsx):```bash
npm run dev
Build TypeScript to `dist/`:```bash
npm run build
Run the compiled server:```bash
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**```bash
echo '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_projects",
"arguments": {
"company_id": 123
}
}
}' | node dist/index.js
- Get a project```bash
echo '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_project",
"arguments": {
"id": 123
}
}
}' | node dist/index.js
- **List RFIs**```bash
echo '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "list_rfis",
"arguments": {
"project_id": 123
}
}
}' | node dist/index.js
- Create RFI```bash
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**```bash
echo '{
"jsonrpc": "2.0",
"id": 5,
"method": "tools/call",
"params": {
"name": "list_submittals",
"arguments": {
"project_id": 123
}
}
}' | node dist/index.js
- Create submittal```bash
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**```bash
echo '{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "list_folders",
"arguments": {
"project_id": 123
}
}
}' | node dist/index.js
- List files```bash
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**```bash
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```bash
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:```json
{
"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:json
{
"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.jsindist/. - env: You can either:
- Inline your secrets here (be cautious), or
- Omit
envso 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.
