@hlao-mcp/bloomerang

MCP server that wraps the Bloomerang REST API and exposes it as typed tools for HLAO agents.

What this MCP connects to

Bloomerang is a donor-management CRM used by nonprofits to track constituents, donations, interactions, and funds. This server wraps the public v2 REST API.

Tools

Read tools (safe; do not mutate Bloomerang state):

| Tool | What it does | | -------------------------- | ------------------------------------------------------------------------------- | | get_constituent_by_id | Fetch a single constituent record by numeric id. | | list_constituents | Page through all constituents. | | search_constituents | Free-text search across constituent name, email, organization. | | get_transaction_history | List a constituent's donations and pledges in reverse chronological order. | | get_donation_by_id | Fetch a single donation transaction. | | list_donations | Page through donations, most recent first. | | get_fund_by_id | Fetch a single fund (designation bucket). | | list_funds | Page through funds. |

Write tools (mutate Bloomerang; require HLAO authority gate):

| Tool | Required passport scope | What it does | | --------------------- | ---------------------------------------- | --------------------------------------- | | create_interaction | bloomerang:create_interaction | Log a new interaction on a constituent. |

Bloomerang holds donor relationship data. Every write tool here is marked side: 'write' and emits a gate_required error if no HLAO passport is presented, or gate_denied if the presented scope does not include the required write scope. The HLAO @hlao/mcp-gateway injects the verified passport from a human-approved review record; production deployments must not bypass that gate.

Credentials

| Variable | What it is | | ------------------------- | ----------------------------------------------------------------------- | | BLOOMERANG_API_KEY | Bloomerang API key (header X-API-KEY). Required. | | BLOOMERANG_API_BASE_URL | API base URL. Defaults to https://api.bloomerang.co/v2. |

How to get the API key

1. Log in to Bloomerang as a user with administrator permissions.
2. Settings → API → Add API Key.
3. Name the key, copy it, and store it in your .env (this directory).

No plan upgrade is required for API access; a paid Bloomerang account in good standing is sufficient.

Local development

cp .env.example .env
# edit .env with your real key
pnpm install
pnpm --filter @hlao-mcp/bloomerang build

# Streamable HTTP transport (production-shaped)
HLAO_MCP_HTTP_PORT=3001 node dist/server.js
# server listens at http://localhost:3001/mcp

# stdio transport for local MCP-client testing
HLAO_MCP_TRANSPORT=stdio node dist/server.js

How HLAO wraps this server

The HLAO @hlao/mcp-gateway is configured to call this server as an MCP client. On every tool call the gateway forwards the verified HLAO passport as the x-hlao-authority header (JSON-encoded { passportId, subject, scope, expiresAt }). This server consumes that header to gate write tools and emits structured errors that flow back through the audit substrate. Tool calls never reach Bloomerang without a verified passport when side: 'write'.