exclugo-mcp 0.1.2

MCP server for the Exclugo healthcare compliance screening platform

Exclugo for Claude

Use Claude (or any AI assistant) to control your Exclugo account — manage facilities, employees, vendors, licenses, billing, reports, and more, just by typing what you want in plain English.

---

Setup (3 steps — about 5 minutes)

You don't need to know how to code. Just follow these steps in order.

Step 1 — Install uv

uv is a tiny tool that runs Exclugo for Claude. You only have to install it once.

On a Mac:

1. Open the Terminal app (press Cmd + Space, type "Terminal", press Enter).

2. Copy and paste this line into Terminal, then press Enter:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Quit Terminal completely (Cmd + Q) and reopen it. This is important.

On Windows:

1. Open PowerShell (press the Windows key, type "PowerShell", press Enter).

2. Copy and paste this line, then press Enter:

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

3. Close PowerShell completely and reopen it.

---

Step 2 — Get your Exclugo API token

Ask your Exclugo administrator to give you an API token. It will look like a long string of letters and numbers, e.g. abc123def456....

(If you'd rather use your normal Exclugo username and password instead, you can — see the "Logging in with username/password" section below.)

---

Step 3 — Tell Claude Desktop about Exclugo

1. Open Claude Desktop.

2. Click the Claude menu at the top → Settings… → Developer → Edit Config.

3. A file called claude_desktop_config.json will open.

4. Paste this in (replace your-token-here with the token from Step 2):

   {
     "mcpServers": {
       "exclugo": {
         "command": "uvx",
         "args": ["exclugo-mcp"],
         "env": {
           "EXCLUGO_BASE_URL": "https://app.exclugo.com",
           "EXCLUGO_API_TOKEN": "your-token-here"
         }
       }
     }
   }
   

   Already have other MCP servers? Just add the "exclugo": { ... } block inside your existing "mcpServers" section.

5. Save the file (Cmd + S or Ctrl + S).

6. Fully quit Claude Desktop (Cmd + Q on Mac) and reopen it.

That's it! You should now see a 🔌 hammer icon at the bottom of the Claude chat box. Click it and you'll see all the Exclugo tools available.

---

Try it out

Type one of these into Claude:

• "Show me all my Exclugo facilities."
• "List the licenses expiring in the next 30 days."
• "Pull up the report for John Smith at Sunrise Care."
• "Show me last month's invoices."
• "Add a new employee named Jane Doe to facility #42, SSN 123-45-6789, born 1980-05-15."

Claude will use Exclugo on your behalf and show you the results.

---

What you can do

You have the same access in Claude that you have when logged into Exclugo on the website. If you're an admin, you can do admin things. If you're a client user, you can do client things. All your existing permissions and restrictions still apply.

You can:

• 📋 Browse your data — facilities, employees, vendors, licenses, NPIs, reports, invoices
• ➕ Add new records — order new background checks, add employees, register licenses
• ✏️ Edit records — update employee info, change facility settings, add notes to reports
• 🔍 Search & filter — find people by SSN, find expiring licenses, search reports
• 📊 View dashboards — alerts, processing status, monitoring summaries
• 💰 Manage billing — view invoices, generate PDFs, run commission reports
• 📅 Manage calendar — create events, send reminders
• ▶️ Trigger monitoring — sex offender, DMF, NPI, exclusion checks
• 📤 Bulk uploads — review upload logs, resolve failed records

---

Logging in with username/password (optional)

If you don't want to use a fixed token, you can have Claude log in for you. In Step 3, leave out the EXCLUGO_API_TOKEN line:

{
  "mcpServers": {
    "exclugo": {
      "command": "uvx",
      "args": ["exclugo-mcp"],
      "env": {
        "EXCLUGO_BASE_URL": "https://app.exclugo.com"
      }
    }
  }
}

Then ask Claude: "Log into Exclugo as username myuser with password mypass." Claude will store the session for you until you close it.

---

Troubleshooting

Claude shows "Failed to spawn process: No such file or directory"

This means uv isn't installed yet, or you didn't restart after installing.

Fix:

1. Re-do Step 1 to install uv.
2. Completely quit Claude Desktop (Cmd + Q on Mac, right-click tray icon → Quit on Windows) and reopen it. Don't just close the window.

If that still doesn't work, find where uv was installed:

• Open Terminal/PowerShell and run: which uvx (Mac/Linux) or where.exe uvx (Windows).

• Copy the full path it shows you (e.g. /Users/yourname/.local/bin/uvx).

• Paste that full path into your config in place of "uvx":

  "command": "/Users/yourname/.local/bin/uvx",
  

Claude says "I don't have access to Exclugo tools"

• Make sure you saved the config file.
• Make sure you fully quit Claude Desktop and reopened it.
• Check the JSON for typos — every quote and bracket matters. Try pasting it into jsonlint.com to verify it's valid.

"401 Unauthorized" when Claude tries to do something

Your token is wrong, expired, or the username/password is incorrect. Get a fresh token from your Exclugo admin.

"403 Forbidden" when Claude tries to do something

You don't have permission for that action. The MCP enforces the same permissions as the Exclugo website — if you can't do something on the website, you can't do it here either. Contact your admin if you need access.

---

For administrators

Generating an API token for a user

From your Exclugo Django shell:

python manage.py shell -c "
from rest_framework.authtoken.models import Token
from django.contrib.auth.models import User
user = User.objects.get(username='THE_USERNAME')
token, created = Token.objects.get_or_create(user=user)
print(f'Token: {token.key}')
"

Send the printed token to the user. They paste it into their config in Step 3.

Permissions

The MCP calls Exclugo's existing REST API — meaning all role-based access controls already enforced by Django apply automatically:

• Admin users → full admin access
• Client users → only their own facilities, restricted by their client_user_settings permissions
• Reseller users → only their reseller's clients
• Free-tier clients → blocked from premium features

You don't need to change any backend code. Whatever a user can do on the website, they can do via Claude.

Publishing a new version (for the package author)

cd exclugo-mcp
# bump version in pyproject.toml first!
rm -rf dist
pip install build twine
python -m build
twine upload dist/*

---

All available tools (~78)

Click to expand the full tool list

Authentication

• authenticate — Log in with username/password

Facilities

list_facilities, get_facility, create_facility, update_facility, delete_facility, get_facility_products, get_facility_fees, get_facility_files, get_facility_report, get_facilities_by_product

Employees

create_employee, edit_employee, search_employees, search_by_ssn, get_employee_address_history

Vendors

create_vendor_individual, create_vendor_organization, edit_vendor, search_vendors

Licenses

create_license, get_expiring_licenses, run_single_license_check, add_manual_license_check, get_license_files, generate_613a_letter, send_613a_email, email_license_status

NPIs

create_npi, edit_npi, search_npis

Reports & Searches

list_reports, get_report, get_report_searches, get_search_detail, get_search_alerts, get_ssn_trace, get_report_history, add_report_note, save_report_document, get_source_lists

Billing

list_invoices, get_invoice, create_invoice_pdf, get_invoice_excel, auto_create_invoices, bulk_invoice_action, get_billing_alerts, list_sales_reps, get_commission_by_month, create_iif_file

Calendar

create_calendar, get_calendar_for_facility, get_calendar_events, get_all_events, calendar_override, send_email_reminder

Users

get_current_user, list_admin_users, get_user_detail, add_client_user, get_client_users, get_user_facilities

Uploads

admin_upload, client_upload, get_upload_logs, get_failed_records, resolve_failed_records

Monitoring triggers

run_exclusion_matching, run_sex_offender_check, run_dmf_check, run_npi_check, run_ssn_plus_exclusion_check, run_ssn_verification

Dashboard / client

get_dashboard, get_client_report, update_alert, disable_monitoring

---

License

MIT