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

``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

$3

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

You should see headlight-mcp processes.

$3

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

Should return {"valid":true}.

$3

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

$3

For local development or custom deployments, add HEADLIGHT_API_URL:

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

Development

`bash


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

`bash
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).