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

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:

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

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

• 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

JOEAPI_BASE_URL=http://localhost:8080  # Local JoeAPI server

Optional (if JoeAPI requires auth)

JOEAPI_API_KEY=your_api_key           # API key for JoeAPI
JOEAPI_USER_ID=1                      # Dev user ID

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:

curl http://localhost:8080/health
# Should return: {"status":"healthy",...}

2. Check MCP server builds:

npm run mcp:build
# Should complete without errors

3. Check Claude Desktop logs:

macOS:

tail -f ~/Library/Logs/Claude/mcp*.log

Windows:

Get-Content $env:APPDATA\Claude\logs\mcp*.log -Wait

4. Test MCP server manually:

npm run mcp:local
# Should output: "JoeAPI MCP Server running locally"
# Press Ctrl+C to stop

Tools Not Appearing in Claude

1. Verify config path is absolute:

"args": ["/Users/joe/dev/joeapi/mcp-build/local-server.js"]

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

2. Check disabled flag:

"disabled": false  // Should be false

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 mcp/index.ts:

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

2. Add handler in CallToolRequest:

   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 prompts array in mcp/index.ts:

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

2. Rebuild and restart

Scripts Reference

# Development
npm run mcp:local     # Run TypeScript directly (tsx)
npm run dev          # Run JoeAPI server

# Production
npm run mcp:build    # Compile TypeScript → JavaScript
npm run mcp:start    # Run compiled JavaScript

# Both
npm run verify-db    # Test database connection

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