JoeAPI is a construction management platform that helps contractors and construction teams manage projects, clients, and business operations through an integrated system. Key capabilities include: - Client and contact management with CRM functionality - Project lifecycle management from proposals and estimates through completion - Action item tracking with supervisor assignments and schedule coordination - Financial monitoring with project summaries and detailed cost views - 18 pre-built workflows for common construction management tasks - 60+ API tools for CRUD operations on construction data The MCP server supports both cloud deployment via Smithery and local STDIO transport for development use.

JoeAPI MCP Server

Model Context Protocol (MCP) server for JoeAPI construction management system. Exposes construction management tools to Claude and other AI assistants.

Overview

This MCP server provides:

Architecture

mcp/
├── index.ts                           # Main MCP server (Smithery + STDIO)
├── local-server.ts                    # STDIO transport runner
├── claude-desktop-config.example.json # Claude Desktop config
├── README.md                          # This file
└── server.ts                          # Legacy (deprecated)
mcp-build/                             # Compiled JavaScript (production)
├── index.js                           # Compiled server
├── local-server.js                    # Compiled STDIO runner
└── *.d.ts                             # TypeScript definitions

Deployment Options

1. Smithery (Cloud) - EXISTING

Your MCP server is already deployed on Smithery for cloud access.

Access: Via Smithery marketplace URL: https://smithery.ai/server/@your-username/joeapi Transport: HTTP Use case: Remote access, team collaboration

2. Local STDIO - THIS SETUP

Run MCP server locally on your machine for development/testing.

Transport: STDIO (Standard Input/Output) Use case: Local development, faster iteration, offline work

---

Local STDIO Setup

Prerequisites

1. JoeAPI running locally:

   npm run dev  # Start JoeAPI on http://localhost:8080
   

2. Build MCP server:

   npm run mcp:build
   

3. Configure Claude Desktop: - Copy mcp/claude-desktop-config.example.json - Update the command path to match your installation - Add to Claude Desktop config

Option A: Development Mode (TypeScript)

For rapid development with auto-recompile:

npm run mcp:local

This runs tsx mcp/local-server.ts - TypeScript executed directly (no build needed).

Option B: Production Mode (Compiled JavaScript)

For production use:

# Build once
npm run mcp:build
Run compiled version
npm run mcp:start

This runs node mcp-build/local-server.js - faster startup, production-ready.

---

Claude Desktop Configuration

Step 1: Find Claude Config Directory

macOS:

~/Library/Application Support/Claude/

Windows:

%APPDATA%\Claude\

Linux:

~/.config/Claude/

Step 2: Edit claude_desktop_config.json

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

Important:

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop. The MCP server will connect automatically.

Step 4: Verify Connection

In Claude Desktop, type:

Can you use the find_workflow tool?

If connected, Claude will have access to all JoeAPI tools.

---

Available Tools

Workflow Discovery (ALWAYS START HERE!)

find_workflow - Discover pre-built workflows

18 Pre-Built Workflows

1. win_loss_rate - Calculate proposal win/loss statistics 2. sales_pipeline - Analyze active proposals in pipeline 3. work_in_process_report - WIP report for active projects 4. job_costing_detail - Detailed job costing analysis 5. project_profitability - Profit analysis by project 6. cost_variance_analysis - Actual vs. estimated cost variance 7. cash_flow_forecast - Project cash flow projections 8. schedule_variance_analysis - Schedule delays and impacts 9. client_portal_update - Generate client progress updates 10. subcontractor_performance - Analyze subcontractor metrics 11. material_tracking - Track material costs and usage 12. labor_productivity - Analyze labor efficiency 13. cost_per_square_foot - Calculate $/sqft by trade 14. change_order_tracking - Track change orders/revisions 15. upgrade_pricing - Price client upgrade requests 16. update_schedule - Extend/adjust project schedules 17. plan_takeoff - Estimate from building plans 18. estimate_from_previous - Create estimate from past job

60+ Individual Tools (Categories)