headlight-mcp-server

MCP server for head·light CRM - connect Claude to your contacts, touchpoints, and reminders.

Setup

1. Generate an API key in head·light Settings → Integrations → AI Integration
2. Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "headlight": {
      "command": "npx",
      "args": ["-y", "headlight-mcp-server"],
      "env": {
        "HEADLIGHT_API_KEY": "your-key-here"
      }
    }
  }
}

3. Restart Claude Desktop

Available Tools

| Tool | Description | |------|-------------| | get_today_summary | Quick overview of today's due items | | search_people | Find contacts by name, journey, or status | | get_person | Full contact details | | add_note | Add a note to a contact | | list_touchpoints | View due/overdue tasks | | complete_touchpoint | Mark a touchpoint done | | list_reminders | View personal reminders | | create_reminder | Create a reminder | | complete_reminder | Mark a reminder done | | list_journeys | See available journeys | | get_journey | Journey details and steps | | assign_journey | Put a contact on a journey |

Example Prompts

• "What's on my head·light agenda today?"
• "Find all my contacts with overdue touchpoints"
• "Add a note to John Smith: Had a great call, interested in the Oak Street listing"
• "Complete the touchpoint for Sarah about the welcome email"
• "Remind me to follow up on the Johnson contract tomorrow"

Troubleshooting

Check if MCP server is running

ps aux | grep -i mcp | grep -v grep

You should see headlight-mcp processes.

Verify API key is valid

curl -s -H "Authorization: Bearer YOUR_API_KEY" https://headlight.marcihoffman.homes/api/mcp/verify

Should return {"valid":true}.

Common issues

| Issue | Cause | Fix | |-------|-------|-----| | Could not resolve host | Wrong API URL | Default is headlight.marcihoffman.homes. Override with HEADLIGHT_API_URL env var | | Invalid API key | Key doesn't exist or wrong tenant | Generate a new key in Settings → Integrations → AI Integration | | Tools not appearing | Claude Desktop not restarted | Restart Claude Desktop after config changes | | Old version cached | npx cache | Run npx -y headlight-mcp-server@latest or clear npm cache |

Using a custom API URL

For local development or custom deployments, add HEADLIGHT_API_URL:

{
  "mcpServers": {
    "headlight": {
      "command": "npx",
      "args": ["-y", "headlight-mcp-server"],
      "env": {
        "HEADLIGHT_API_KEY": "your-key-here",
        "HEADLIGHT_API_URL": "http://localhost:3000"
      }
    }
  }
}

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Test locally
HEADLIGHT_API_KEY=your-key HEADLIGHT_API_URL=http://localhost:3000 node dist/index.js

Publishing

cd packages/mcp-server
# Update version in package.json
pnpm build
npm publish --access public

Note: Will prompt for security key authentication. Users get updates automatically on next Claude Desktop restart (npx fetches latest).