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
-
JoeAPI running locally:
npm run dev # Start JoeAPI on http://localhost:8080 -
Build MCP server:
npm run mcp:build -
Configure Claude Desktop:
- Copy
mcp/claude-desktop-config.example.json - Update the
commandpath to match your installation - Add to Claude Desktop config
- Copy
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: falseto see ALL 18 workflows - Set
autoExecute: truewith workflow name to get step-by-step instructions
18 Pre-Built Workflows
win_loss_rate- Calculate proposal win/loss statisticssales_pipeline- Analyze active proposals in pipelinework_in_process_report- WIP report for active projectsjob_costing_detail- Detailed job costing analysisproject_profitability- Profit analysis by projectcost_variance_analysis- Actual vs. estimated cost variancecash_flow_forecast- Project cash flow projectionsschedule_variance_analysis- Schedule delays and impactsclient_portal_update- Generate client progress updatessubcontractor_performance- Analyze subcontractor metricsmaterial_tracking- Track material costs and usagelabor_productivity- Analyze labor efficiencycost_per_square_foot- Calculate $/sqft by tradechange_order_tracking- Track change orders/revisionsupgrade_pricing- Price client upgrade requestsupdate_schedule- Extend/adjust project schedulesplan_takeoff- Estimate from building plansestimate_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:
-
Claude Desktop config (recommended):
"env": { "JOEAPI_BASE_URL": "http://localhost:8080" } -
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
-
Edit
mcp/index.ts:{ name: 'my_new_tool', description: 'Description of tool', inputSchema: { type: 'object', properties: { param1: { type: 'string', description: '...' } }, required: ['param1'] } } -
Add handler in
CallToolRequest:case 'my_new_tool': { const { param1 } = args as { param1: string }; result = await callJoeAPI(baseUrl, `/api/v1/endpoint`); break; } -
Rebuild:
npm run mcp:build -
Restart Claude Desktop
Adding New Workflows
-
Add to
promptsarray inmcp/index.ts:{ name: 'my_workflow', description: 'Brief description', arguments: [...], prompt: 'WORKFLOW: My Workflow\n\nPURPOSE: ...\n\nSTEPS:\n1. ...' } -
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
| Feature | Smithery (Cloud) | Local STDIO |
|---|---|---|
| Setup | Already deployed | Requires local setup |
| Access | Remote, anywhere | Local machine only |
| Speed | Network latency | Instant (local) |
| Availability | Always on | Requires JoeAPI running |
| Updates | Auto-deployed | Manual build required |
| Collaboration | Team access | Single user |
| Best for | Production, team | Development, testing |
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