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.