JoeAPI

You can think of the JoeAPI MCP Server as a bridge between your JoeAPI construction management data and AI assistants like Claude. It exposes a rich set of pre-built workflows and direct API tools, all accessible through local STDIO or cloud-based Smithery deployments. This allows you to automate common construction tasks, retrieve up-to-date project information, and integrate AI-driven insights into your workflows.

How to use

You connect to the MCP server from your preferred MCP client. If you are using a cloud deployment, you access it via the Smithery marketplace and communicate over HTTP. For local development and testing, you run the local STDIO transport so the MCP server talks to you through Standard Input/Output on your machine.

Start by discovering available workflows. Use the find_workflow tool to list the 18 pre-built workflows and, if you want to see all details, set autoExecute to false. When you know a workflow name, you can trigger it and Claude will guide you through each step. You can also call any of the 60+ individual tools to read or mutate data directly in JoeAPI.

How to install

Prerequisites: you need Node.js installed, and JoeAPI must be running for the MCP server to connect to data.

Install JoeAPI dependencies and start JoeAPI server locally

npm install npm run dev

Build and run the MCP server locally in STDIO mode

npm run mcp:build npm run mcp:start

## Local STDIO setup notes

Use the local STDIO transport to run the MCP server on your machine. Claude Desktop will connect to the local server using STDIO.

Two key commands you’ll use during development are shown here for convenience.

Option A: Development mode (TypeScript)

npm run mcp:local

Option B: Production mode (compiled JavaScript)

# Build once
npm run mcp:build

# Run compiled version
npm run mcp:start

Claude Desktop configuration and connection

You connect Claude Desktop to the local MCP server by adding a config entry that points to the compiled local server. Use absolute paths and set the base URL so Claude knows where to send requests.

Example Claude Desktop config entry

{ "mcpServers": { "joeapi-local": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/joeapi/mcp-build/local-server.js" ], "env": { "JOEAPI_BASE_URL": "http://localhost:8080" }, "disabled": false } } }

## Environment variables

Set the base URL for JoeAPI in Claude Desktop and optionally supply an API key and user ID if JoeAPI requires authentication.

Required

JOEAPI_BASE_URL=http://localhost:8080

Optional (if JoeAPI requires auth)

JOEAPI_API_KEY=your_api_key
JOEAPI_USER_ID=1

Troubleshooting

If the MCP server isn’t connecting, verify JoeAPI is running, ensure the MCP server has been built, and check Claude Desktop logs for errors. You can also test the local MCP server manually to confirm it starts and responds.

Development tips

If you want to extend JoeAPI with new tools or workflows, edit the MCP source, rebuild, and restart Claude Desktop so the new capabilities appear to your AI assistant.

Available tools

find_workflow

Discover pre-built workflows. Set autoExecute to false to see all 18 workflows; set autoExecute true with a workflow name to execute it step-by-step.

win_loss_rate

Workflow to calculate proposal win/loss statistics.

sales_pipeline

Workflow to analyze active proposals in the sales pipeline.

work_in_process_report

Workflow to generate a WIP report for active projects.

job_costing_detail

Workflow for detailed job costing analysis.

project_profitability

Workflow to analyze profitability by project.

cost_variance_analysis

Workflow to analyze actual vs estimated cost variance.

cash_flow_forecast

Workflow to project cash flow projections.

schedule_variance_analysis

Workflow to assess schedule delays and their impacts.

client_portal_update

Workflow to generate client progress updates.

subcontractor_performance

Workflow to analyze subcontractor metrics.

material_tracking

Workflow to track material costs and usage.

labor_productivity

Workflow to analyze labor efficiency.

cost_per_square_foot

Workflow to calculate $/sqft by trade.

change_order_tracking

Workflow to track change orders and revisions.

upgrade_pricing

Workflow to price client upgrade requests.

update_schedule

Workflow to extend or adjust project schedules.

plan_takeoff

Workflow to estimate from building plans.

estimate_from_previous

Workflow to create an estimate from a past job.

Clients CRUD

Create, read, update, and delete client records.

Contacts CRUD

Manage client contacts.

SubContractors CRUD

Manage subcontractor records.

Proposals CRUD

Create and track proposals.

Estimates CRUD

Manage project estimates.

ProjectManagements CRUD

Manage active project data.