Lgl MCP Server

Little Green Light (LGL) MCP Server

A direct, secure, and high-fidelity Model Context Protocol (MCP) Server for the Little Green Light CRM database. This server allows AI coding assistants and chat applications (like Claude Desktop, LibreChat, or Open WebUI) to securely interact with your donor database to search constituents, log gifts, categorize taxonomic groups, and generate reports locally without any third-party middleware (like Zapier).

---

Features

• Constituents & Core Management: Search, retrieve, create, update, and delete constituent records. create_constituent rejects a fully blank identity (needs organization_name, or at least one of first_name/last_name) rather than silently creating an empty record. Bulk name-resolution helpers (used to label aggregate reports like top_donors) distinguish a genuine "constituent doesn't exist" from any other lookup failure (rate limit, network, auth) instead of masking both as the same fallback.
• Advanced Server-Side Search: search_constituents_advanced filters constituents directly through LGL's own query engine — custom attributes (contains/equals/starts-with/blank/not-blank), keyword, location, membership status/level, groups, lists, and updated date — all AND'd together and referenced by friendly display name rather than internal LGL IDs. Attribute values are only included in results when explicitly requested (include_custom_attrs), keeping ordinary filtered lookups lightweight. constituents_never_touched_attribute finds records that have never had a given custom attribute set at all — a state LGL's own blank/not-blank operators can't distinguish from "set but empty." constituents_missing_info walks the full constituent list (not just the first page) to find records missing an email, phone, or address, and returns count separately from the limit-sliced results, flagging truncated if the account is large enough to hit the underlying scan's page cap.
• Fundraising & Gifts: Record new gifts, list transactions (with date-range filters), search payments, and view campaigns, funds, appeals, and events. Gift/donor-lookup tools surface each record's gift type and pledge/installment linkage, and giving-total reports exclude pledges from cash totals to avoid double-counting — see Gift Types & Pledge Linkage below.
• Contact Sub-Resources: Fully manage street addresses, phone numbers, email addresses, and web addresses for constituents.
• Activities & Notes: Log notes, write contact reports, and track volunteer hours.
• Groups & Memberships: Organize constituents into customizable groups and membership levels.
• One-Shot Donor Lookup: get_donor_context returns profile + recent gifts + group memberships + recent notes in a single call (resolves by name or ID).
• Full Profile Export: export_constituent_profile mirrors LGL's own "Export Profile" button — full record, complete gift history, relationships, class/school affiliations, memberships, volunteer time, contact reports, appeal requests, event invitations, group memberships, and notes, fetched in parallel in one call.
• Document Links: log_document_link records a note pointing at a file hosted elsewhere (OneDrive/SharePoint/etc.) — LGL's API has no file-upload endpoint, so this is a reference, not a real attachment. See API Gaps & Workarounds below.
• Groups as Saved Lists: create_group_with_members creates a group and adds constituents to it in one call — the closest API-native substitute for LGL's UI-only dynamic Lists, which have no create/edit endpoint. Membership writes are batched (20 at a time) rather than fired all at once, so a large constituent list doesn't blast the API with unbounded concurrent requests. See API Gaps & Workarounds below.
• Three Permission Levels: strictly read-only, assisted (read-only plus notes and human-reviewed webhook writes), and full. See Permission Levels below.
• Access Audit Trail: get_constituent, get_donor_context, and export_constituent_profile automatically log when they're used — as an [AI Access Log] note on the constituent's LGL record, or as a row in a local Excel file, depending on LGL_ACCESS_LOG_DESTINATION. See Access Audit Logging below.
• Human-Reviewed Writes: Five submit_*_for_review tools post to LGL's own Integration Queue webhook instead of the API, so a person approves every write in LGL before it takes effect. Available in full mode and assisted mode. See Human-Reviewed Writes below.
• Zero-Middleware Architecture: Data transits directly between the local AI client and the LGL API, reducing security risks and third-party fees.

---

Installation & Setup

1. Prerequisites

• Node.js (v18 or higher recommended)
• A Little Green Light API Key (Generate one in your LGL account under *Settings > Integration > API Keys*)

2. Install Dependencies

Clone this repository to your local machine, open a terminal in the folder, and run:

npm install

3. Configure Environment Variables

Copy the .env.example template to create your local .env configuration file:

cp .env.example .env

Open .env in a text editor and replace the placeholder with your actual LGL API key and configuration:

LGL_API_KEY=your_lgl_api_key_here

PORT=3000

Optional: Secure your Streamable HTTP endpoint with Bearer Token Authentication

LGL_MCP_TOKEN=your_secure_bearer_token_here

Optional: enables the submit_*_for_review tools — see "Human-Reviewed Writes" below

LGL_INTEGRATION_LISTENER_URL=https://your-account.littlegreenlight.com/integrations/your-integration-id/listener

Optional: field-name casing for submit_*_for_review payloads — "snake"

(default) or "title" — see "Human-Reviewed Writes" below

LGL_INTEGRATION_FIELD_CASE=snake

Optional: choose where the automatic access-audit trail is logged —

"lgl_note" (default) writes a note directly to LGL, "excel" appends a row

to a local spreadsheet instead. See "Access Audit Logging" below.

LGL_ACCESS_LOG_DESTINATION=lgl_note

Required only when LGL_ACCESS_LOG_DESTINATION=excel — absolute path to the

.xlsx file to append access-log rows to.

LGL_ACCESS_LOG_PATH=C:\path\to\AI_Access_Log.xlsx

Permission Levels

Two env vars combine to give three permission levels:

# Strictly read-only

LGL_READ_ONLY=true

Assisted: read-only plus notes and human-reviewed webhook writes

LGL_READ_ONLY=true LGL_ASSISTED_MODE=true

In both read-only and assisted mode, disallowed tools are hidden from tools/list (not just rejected on call) so the AI assistant doesn't try to use them. LGL_ASSISTED_MODE has no effect unless LGL_READ_ONLY=true is also set — in full mode everything it unlocks is already available. Recommended whenever you point the server at a live donor database: use strictly read-only for pure exploratory sessions, assisted when you also want the access-audit trail and human-reviewed writes to work.

All tools also publish MCP annotations (readOnlyHint, destructiveHint, idempotentHint) so clients can warn before destructive calls without depending on the server-side guard.

---

Access Audit Logging

Whenever get_constituent, get_donor_context, or export_constituent_profile is called, the server logs the access for audit purposes. Where that log goes is controlled by LGL_ACCESS_LOG_DESTINATION:

• `lgl_note` (default): writes a note directly to that constituent's record in LGL — e.g. [AI Access Log] Record accessed via LGL MCP Server (get_constituent) on 2026-07-13 17:24 UTC. It rides along with whichever permission level is active, and is silently skipped under strictly read-only, where the whole point is to leave zero footprint on LGL.
• `excel`: appends a row (timestamp, tool, constituent ID, constituent name) to the .xlsx file at LGL_ACCESS_LOG_PATH instead. Fires in every mode, including strictly read-only, since it never writes to LGL at all.

Deactivating a note type in LGL's UI (Settings → Menu Items → Note Types) does not hide existing notes of that type from a constituent's activity view, and the API can still write new notes using a deactivated type's ID — so deactivating the note type used for lgl_note logging doesn't reduce clutter, it only keeps that type out of the manual "new note" dropdown for staff. If note clutter on constituent records is the concern, switch to excel instead.

A few things worth knowing:

• Scope is single-record detail views only. Bulk list_*/search_* calls do *not* log — noting every row of a 50-record list would flood the log with little audit value. Only tools that open one specific donor's file do.
• Best-effort, either destination: if writing the log entry fails for any reason, the read that triggered it still succeeds; the failure is logged to stderr, not surfaced as a tool error. For excel, a locked file (e.g. open in Excel) is retried a few times before giving up.
• `lgl_note` writes directly via the API, not through the Integration Queue — an audit trail that needed human approval to appear defeats the purpose. It also needs an existing note_type_id (a number), not a type name — passing a name is silently ignored by LGL rather than applied. The server resolves this at runtime (preferring a type literally named "General", falling back to whatever type exists first) rather than hardcoding an ID, since type IDs are account-specific. This same fix applies to create_note/update_note, which previously accepted a note_type string that never actually applied — invalid type names now raise a clear error instead of silently creating an untyped note.
• `excel` creates the file if it doesn't exist, with a bold, frozen header row (Timestamp, Tool, Constituent ID, Constituent Name), and keeps growing indefinitely — there's no automatic rotation or archiving.
• `excel` isn't safe under heavy concurrency: each write reads and rewrites the whole file with no locking, so two truly simultaneous accesses could race and one could silently overwrite the other's row. This is an accepted trade-off for a best-effort audit log — not expected to matter for typical single-client usage, but worth knowing if you're logging from multiple concurrent MCP sessions against the same file.

---

Human-Reviewed Writes (Integration Queue)

Separate from the direct LGL API, LGL also has a custom integration webhook feature (LGL Settings → Integrations → Custom Integrations) that accepts flat key/value submissions and drops them into an Integration Queue for a human to approve before anything is actually written to a constituent's record. This server exposes that path as five tools, distinct from the create_*/update_* API tools:

| submit_constituent_for_review | Iden