Lgl 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.
• Fundraising & Gifts: Record new gifts, list transactions (with date-range filters), search payments, and view campaigns, funds, appeals, and events.
• 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. 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 write an [AI Access Log] note directly to the constituent's record noting when it was viewed, in full and assisted modes. 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

Permission Levels

Two env vars combine to give three permission levels:

Level	LGL_READ_ONLY	LGL_ASSISTED_MODE	What's allowed
Strictly read-only	true	unset/false	Reads only. Zero writes of any kind — no direct mutations, no notes (including the automatic access-audit note), no Integration Queue submissions.
Assisted	true	true	Everything read-only allows, plus low-risk, easily-reviewed writes: the automatic access-audit notes, explicit create_note/update_note/log_document_link, and the submit_*_for_review Integration Queue tools. Direct mutations to constituents/gifts/groups/etc. (including create_group_with_members) stay blocked.
Full	unset/false	(ignored)	Unrestricted — every tool, including direct create_*/update_*/delete_* mutations.

# 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 in full or assisted mode, the server 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's not a config option of its own — 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.

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 constituents' note history with little audit value. Only tools that open one specific donor's file do.
• The note writes directly via the API, not through the Integration Queue — an audit trail that needed human approval to appear defeats the purpose.
• Best-effort: if writing the note fails for any reason, the read that triggered it still succeeds; the failure is logged to stderr, not surfaced as a tool error.
• Note type: LGL's write API 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.

---

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:

Tool	Covers
submit_constituent_for_review	Identity/name fields, up to 3 phone numbers, up to 3 emails, up to 2 mailing addresses, a website, constituent category fields, and a relationship
submit_gift_for_review	Gift, pledge, and goal fields, plus tribute (honor/memorial) details
submit_note_for_review	Notes
submit_event_registration_for_review	Event registrations/invitations
submit_appeal_request_for_review	Appeal requests

None of these five write to LGL directly — every submission lands in Settings → Integration Queue → Unsaved in LGL, where someone reviews and either saves or rejects it. Because of that, they only need assisted mode rather than full write access: LGL_READ_ONLY=true with LGL_ASSISTED_MODE=true is enough to use them, since they can't change data without a human clicking Save in LGL first. Strictly read-only mode (no LGL_ASSISTED_MODE) still blocks them, since they are real writes to a shared queue.

Setup:

1. In LGL, go to Settings → Integrations and create (or reuse) a Custom Integration. Copy its listener URL.
2. Set LGL_INTEGRATION_LISTENER_URL to that URL in your environment.
3. In that integration's field mapping screen, map the field names your submissions will use (e.g. first_name, phone, email_2, gift_amount, note_text) to the corresponding LGL fields. The mapping lives entirely in LGL's UI, not in this server — a field that isn't mapped is silently ignored by LGL rather than causing an error, so an unmapped submission may look successful (HTTP 200) while carrying no usable data. Repeating fields (phone/email/address) use LGL's "Record Type / #" grouping: slot 1 is the bare field name (phone, email), slots 2–3 use a numeric suffix (phone_2, email_3).
4. Because there's no LGL account whose mapping is identical out of the box, treat the field names above as a starting point and confirm against your own mapping screen before relying on a given tool.

Known limitation: mapping a field to "LGL constituent ID" to match/update an existing constituent by ID does not currently persist, at least when the integration's record-matching preference is set to email/name-based matching rather than ID-based. Matching therefore relies on first_name + last_name + email instead — omit any ID field from your mapping.

---

API Gaps & Workarounds

Some things LGL's own web UI supports have no equivalent anywhere in LGL's API — not the REST API, and not the Integration Queue webhook (which only accepts constituent/gift/note/event-registration/appeal-request fields). Confirmed absent as of this writing:

UI Feature	API endpoint?	Webhook field mapping?	This server's approach
Tasks / to-dos / reminders assigned to team members	No	No	None. There's no way to reach LGL's Tasks feature (including its reminder emails) programmatically — an actual feature request to LGL Support is the only path forward.
File/document attachments on a constituent record	No	No	log_document_link logs a note containing a link to a file hosted elsewhere (OneDrive, SharePoint, Google Drive, etc.) plus a description. This is a reference, not a real attachment — LGL cannot accept an uploaded file via API at all; even its own web forms only accept a hosted URL, never raw file bytes.
Saved Lists (dynamic, re-runnable queries)	No (read-only at best)	No	create_group_with_members creates an LGL group (a static set of constituents) and adds members to it in one call. Groups are fully API-writable and serve a similar purpose — "a set of people to come back to" — but are static membership, not a live query. Add/remove members afterward with add_constituent_to_group / remove_constituent_from_group.

---

Transport Selection

This server supports two communication transport standards:

• Stdio Transport (Default): The standard input/output process channel. Ideal for local programs like Claude Desktop or local command configurations.
• Streamable HTTP Transport (SSE): Runs a native HTTP server providing modern, stateful Server-Sent Events (SSE) over HTTP. Required for GitHub Copilot, Cursor's SSE mode, cloud containers, and systems that don't natively execute local Node.js processes.

Running in Streamable HTTP Mode

To launch the server in Streamable HTTP mode, use the --http (or --sse) flag:

node index.js --http --port 3000

• Port Selection: Custom ports can be specified using --port <number> or the PORT environment variable (defaults to 3000).
• Secure Token Protection: If you set LGL_MCP_TOKEN in your .env file, Bearer Token Authentication is strictly enforced. All client requests must include the header Authorization: Bearer <your_token>, or they will be rejected with 401 Unauthorized.

---

Integrating with AI Clients

This server can be integrated into any AI client, editor, or chat interface that supports the Model Context Protocol (MCP).

1. Claude Desktop

To utilize this server in the official Claude Desktop application, add the configuration to your claude_desktop_config.json file.

File Location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "lgl-crm": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\workspace\\folder\\index.js"],
      "env": {
        "LGL_API_KEY": "your_lgl_api_key_here"
      }
    }
  }
}

2. Cursor IDE (AI Code Editor)

Cursor supports custom MCP servers directly in its graphical user interface. You can connect using either Stdio (command) or Streamable HTTP (SSE):

Option A: Local Stdio (Command)

1. Open Cursor and navigate to Settings > Features > MCP.
2. Click + Add New MCP Server.
3. Configure the fields in the popup:
   • Name: lgl-crm
   • Type: command
   • Command: node C:\path\to\your\workspace\folder\index.js
4. Click Save. Note: You must ensure that the LGL_API_KEY is set in your operating system environment variables or shell configuration so Cursor can inherit it.

Option B: Streamable HTTP (SSE Mode)

1. Start the LGL MCP server in HTTP mode: node index.js --http --port 3000
2. Navigate to Settings > Features > MCP.
3. Click + Add New MCP Server.
4. Configure the fields in the popup:
   • Name: lgl-crm-sse
   • Type: sse
   • URL: http://localhost:3000/mcp
5. Click Save. Note: If LGL_MCP_TOKEN is enabled, ensure your editor includes the Bearer authorization header or connection config.

3. Windsurf IDE (AI Code Editor)

Windsurf supports native MCP configurations via its global config file.

File Location:

• Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
• macOS/Linux: ~/.codeium/windsurf/mcp_config.json

Configuration:

{
  "mcpServers": {
    "lgl-crm": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\workspace\\folder\\index.js"],
      "env": {
        "LGL_API_KEY": "your_lgl_api_key_here"
      }
    }
  }
}

4. LibreChat (Open-Source Chat UI)

LibreChat allows you to integrate MCP servers directly through its centralized config file librechat.yaml.

Configuration in librechat.yaml:

mcpServers:
  lgl-crm:
    type: "stdio"
    command: "node"
    args: ["C:\\path\\to\\your\\workspace\\folder\\index.js"]
    env:
      LGL_API_KEY: "your_lgl_api_key_here"

5. Open WebUI (Local/Self-Hosted AI UI)

To add this to Open WebUI (commonly used with local Ollama instances):

1. Navigate to Admin Settings > Connections > MCP.
2. Click Add Connection.
3. Name the connection lgl-crm.
4. Enter the command configuration:
   • Command: node C:\path\to\your\workspace\folder\index.js
5. Click Submit. (Make sure the environment variable LGL_API_KEY is loaded on your host machine or docker run statement running the Open WebUI instance).

---

Security & Data Privacy

Unlike other MCP integrations that route sensitive donor information through third-party services (like Zapier or Make), this server operates on a direct local pipeline:

• Zero Third-Party Storage: All constituent data, physical addresses, emails, phone numbers, and financial donations are sent directly from your computer to the official LGL API over secure, encrypted HTTPS.
• Principle of Least Privilege: You can easily restrict access to database modifications (e.g. deleting records) by commenting out or removing the corresponding tools in the index.js file before deployment.

---

License

This project is open-source and free to adapt for non-profit organizations under the MIT License.