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:

• 18 pre-built workflows for common construction management tasks

• 60+ individual tools for direct API access (CRUD operations)

• Multi-transport support: Smithery (cloud) and STDIO (local)

Architecture

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:

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

Option B: Production Mode (Compiled JavaScript)

For production use:

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

Claude Desktop Configuration

Step 1: Find Claude Config Directory

macOS:

Windows:

Linux:

Step 2: Edit claude_desktop_config.json

Important:

• Use absolute paths (not relative like ~/ or ./)

• Change /ABSOLUTE/PATH/TO/joeapi/ to your actual path

• Example: /Users/joe/dev/joeapi/mcp-build/local-server.js

Step 3: Restart Claude Desktop

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

Step 4: Verify Connection

In Claude Desktop, type:

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

Available Tools

Workflow Discovery (ALWAYS START HERE!)

find_workflow - Discover pre-built workflows

• Set autoExecute: false to see ALL 18 workflows

• Set autoExecute: true with workflow name to get step-by-step instructions

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)

• Clients - CRUD operations for clients

• Contacts - Manage client contacts

• SubContractors - Subcontractor management

• Proposals - Create and track proposals

• ProposalLines - Line items within proposals

• Estimates - Project estimates

• ProjectManagements - Active project data

• ProjectSchedules - Project timelines

• ProjectScheduleTasks - Individual tasks

• ActionItems - Track action items with:

  • Comments

  • Supervisors

  • Cost changes

  • Schedule changes

• Transactions - QuickBooks transaction data

• JobBalances - Current job balances

• CostVariance - Cost variance analysis

• Invoices - Invoice management

• ScheduleRevisions - Schedule change tracking

• ProjectDetails - Comprehensive project data

• ProposalPipeline - Pipeline analytics

• EstimateRevisions - Estimate change history

• CostRevisions - Cost revision tracking

• Deposits - Deposit/retainer management

• ProposalTemplatePricing - Standard pricing templates

Environment Variables

Required

Optional (if JoeAPI requires auth)

Set these in:

1. Claude Desktop config (recommended):

   "env": { "JOEAPI_BASE_URL": "http://localhost:8080" }

2. Shell environment (alternative):

   export JOEAPI_BASE_URL=http://localhost:8080

Troubleshooting

MCP Server Not Connecting

1. Check JoeAPI is running:

2. Check MCP server builds:

3. Check Claude Desktop logs:

macOS:

Windows:

4. Test MCP server manually:

Tools Not Appearing in Claude

1. Verify config path is absolute:

Not: ["~/dev/joeapi/mcp-build/local-server.js"] ❌

2. Check disabled flag:

3. Restart Claude Desktop:

• Close completely (Cmd+Q on macOS)

• Reopen

4. Check for errors in MCP logs

JoeAPI Connection Errors

Error: JoeAPI error (401)

• JoeAPI requires authentication

• Add API key or dev user ID to config

Error: JoeAPI error (404)

• Endpoint not found

• Check JoeAPI version matches MCP server

Error: ECONNREFUSED

• JoeAPI not running

• Start with: npm run dev

Development

Adding New Tools

1. Edit

   { name: 'my_new_tool', description: 'Description of tool', inputSchema: { type: 'object', properties: { param1: { type: 'string', description: '...' } }, required: ['param1'] } }

2. Add handler in

   case 'my_new_tool': { const { param1 } = args as { param1: string }; result = await callJoeAPI(baseUrl, `/api/v1/endpoint`); break; }

3. Rebuild:

   npm run mcp:build

4. Restart Claude Desktop

Adding New Workflows

1. Add to

   { name: 'my_workflow', description: 'Brief description', arguments: [...], prompt: 'WORKFLOW: My Workflow\n\nPURPOSE: ...\n\nSTEPS:\n1. ...' }

2. Rebuild and restart

Scripts Reference

Comparison: Smithery vs Local STDIO

Support

• MCP SDK Docs: https://modelcontextprotocol.io

• Claude Desktop MCP Guide: https://docs.claude.com/docs/mcp

• JoeAPI Issues: Check GitHub repo

• MCP Server Code: mcp/index.ts