hawksoft-mcp

Model Context Protocol (MCP) server for HawkSoft Insurance Agency Management.

Talk to your HawkSoft data from Claude, Cursor, or any MCP client — read clients, policies, and claims, and write back log notes, attachments, and receipts in plain English.

Built against the HawkSoft Partner API v3.0. No existing MCP for HawkSoft — this is the first.

What you can do with it

You:  "Show me every HawkSoft client modified since Monday and group them by carrier."

Claude:  *calls list_changed_clients, then get_client for each, then summarises*

You:  "Find the policy POR83741 and log a phone call with the insured about their renewal."

Claude:  *searches by policy → opens client → calls create_log_note with channel=5*

Other things agents do well with this server:

• Pre-call briefs — pull the client's full history (policies, claims, prior conversations) before a phone call

• Auto-document carrier touchpoints — every email/phone with a carrier becomes a structured log note

• Batch activity reporting — "give me a weekly summary of every client I called"

• Certificate of insurance / declaration page intake — attach PDFs straight into the right client record

• Reconciliation help — surface clients with outstanding invoices, draft follow-ups

Related MCP server: QuickBooks Online MCP Server

Install

pip install -e .

Or just use uv / pipx if you prefer.

Configure

You need HawkSoft Partner API credentials — username + password issued by HawkSoft after your app is approved through their Partner Program.

export HAWKSOFT_USERNAME="your-vendor-username"
export HAWKSOFT_PASSWORD="your-vendor-password"

You can also drop these in a .env file (see .env.example).

Who uses this server?

Two audiences:

1. Approved HawkSoft API Partners building tools for independent agencies. Your vendor credentials work directly.

2. Independent agencies doing their own custom integration work. HawkSoft has explicitly opened this path — see the V3.0 launch post:

   "any agencies who build their own custom API integrations" can use the V3.0 Partner API directly.

   If you're an agency and don't have vendor credentials yet, email opportunities@hawksoft.com to get set up.

Use with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hawksoft": {
      "command": "hawksoft-mcp",
      "env": {
        "HAWKSOFT_USERNAME": "your-vendor-username",
        "HAWKSOFT_PASSWORD": "your-vendor-password"
      }
    }
  }
}

Restart Claude Desktop. You should see 9 new tools + 1 resource (hawksoft://channels).

Use with Claude Code

claude mcp add hawksoft -- hawksoft-mcp \
  --env HAWKSOFT_USERNAME=your-user --env HAWKSOFT_PASSWORD=your-pass

Use with Cursor

Add a new MCP server in Cursor settings pointing at the hawksoft-mcp command with the same env vars.

Tools

Plus one resource:

Common patterns

Pre-call brief

User:  I'm about to call client 4231. Give me the full picture.
Agent: list_changed_clients(agency_id=1, as_of="2020-01-01")
       → [4231, ...]
       get_client(agency_id=1, client_id=4231)
       → returns details, policies, people, prior claims
       summarise: 2 personal auto policies, 1 umbrella, no recent claims, last contact 2 weeks ago about a billing question...

Document a phone call after it happens

User:  I just got off a call with the Johnsons about their renewal. Auto policy. Renewal looks good, they want to add a teenage driver next month.
Agent: search_client_by_policy(agency_id=1, policy_number="AUTO-7741")
       → finds client
       create_log_note(
           agency_id=1,
           client_id=client_id,
           channel="Phone From Insured",
           description="Renewal discussion; wants to add teen driver next month",
           body="Discussed upcoming renewal. Customer satisfied with current rate. Mentioned adding a teenage driver in ~30 days. Set follow-up task for CSR to send driver addition intake form.",
           task_title="Send teen driver intake form",
           task_description="Customer mentioned adding teenage driver to auto policy next month. Send standard intake form.",
           task_due_date="2026-07-15",
           task_assigned_to_role="CSR",
       )

End-of-day activity digest

User:  What did I do with clients today?
Agent: create_log_note(...) for each touchpoint during the day,
       then for the digest: get_clients_bulk(client_numbers=[recent_ids])
       and summarise.

Channel catalog

Channels use friendly names everywhere in the API — never the integer. Phone From Insured, Email To Carrier, etc. The full 56-entry catalog is exposed via the list_channels_tool tool and the hawksoft://channels resource.

API coverage

Full HawkSoft Partner API v3.0 docs: https://partner.hawksoft.app/v3/api.html

Development

# install with dev deps
pip install -e ".[dev]"

# run tests
pytest

# run server locally (stdio)
hawksoft-mcp

If you don't have HawkSoft credentials yet, the client will raise a clear error on first call — the server doesn't try to connect at import time.

License

MIT — see LICENSE.

Contributing

Issues + PRs welcome. Two things that always help:

1. More tools. If you spot a HawkSoft endpoint we missed (or one that needs a friendlier wrapper), open an issue.

2. Better prompts. The most useful thing you can share is a real example of an insurance workflow this helped you with — we collect these in /examples.

See also

• HawkSoft Partner API V3.0 docs

• HawkSoft partner program

• Model Context Protocol spec

• MCP Python SDK