wegive-mcp

MCP (Model Context Protocol) server for the WeGive API. Enables Claude to interact with WeGive nonprofit fundraising data.

Installation

npm install wegive-mcp

Setup

Claude Desktop

Add to your config file:

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

With API access (for all tools):

{
  "mcpServers": {
    "wegive": {
      "command": "npx",
      "args": ["wegive-mcp"],
      "env": {
        "WEGIVE_API_KEY": "your_api_key"
      }
    }
  }
}

Knowledge tool only (no API key needed):

{
  "mcpServers": {
    "wegive": {
      "command": "npx",
      "args": ["wegive-mcp"],
      "env": {
        "WEGIVE_KNOWLEDGE_API_KEY": "your_knowledge_api_key",
        "WEGIVE_DEFAULT_PERSONA": "customer"
      }
    }
  }
}

Claude Code

Add to .claude/settings.local.json:

With API access (for all tools):

{
  "mcpServers": {
    "wegive": {
      "command": "npx",
      "args": ["wegive-mcp"],
      "env": {
        "WEGIVE_API_KEY": "your_api_key"
      },
      "alwaysAllow": ["*"]
    }
  }
}

Knowledge tool only (no API key needed):

{
  "mcpServers": {
    "wegive": {
      "command": "npx",
      "args": ["wegive-mcp"],
      "env": {
        "WEGIVE_KNOWLEDGE_API_KEY": "your_knowledge_api_key",
        "WEGIVE_DEFAULT_PERSONA": "customer"
      },
      "alwaysAllow": ["*"]
    }
  }
}

The alwaysAllow setting auto-approves all wegive MCP tools so you won't be prompted for each call.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | WEGIVE_API_KEY | No* | Your WeGive API key (required for API tools, not needed for knowledge tool) | | WEGIVE_SANDBOX | No | Set to true for sandbox environment | | WEGIVE_KNOWLEDGE_API_KEY | No | API key for Product Knowledge queries | | WEGIVE_DEFAULT_PERSONA | No | Default persona for wegive_knowledge when not supplied (engineering, cs, sales, customer, documentation) |

*At least one API key (WEGIVE_API_KEY or WEGIVE_KNOWLEDGE_API_KEY) should be configured for the server to be useful.

Getting Your API Key

1. Log in to your WeGive Dashboard
2. Navigate to Settings > Integrations
3. Generate or copy your API key

Available Tools

Donors

• wegive_list_donors - List donors with filtering
• wegive_get_donor - Get donor details
• wegive_find_or_create_donor - Find or create a donor
• wegive_ask_donor_ai - Ask AI about a donor

Transactions

• wegive_list_transactions - List donations
• wegive_get_transaction - Get transaction details

Recurring Donations

• wegive_list_scheduled_donations - List recurring gifts
• wegive_get_scheduled_donation - Get recurring donation details

Campaigns

• wegive_list_campaigns - List campaigns
• wegive_get_campaign - Get campaign details

Campaign Events

• wegive_list_campaign_events - List events
• wegive_get_campaign_event - Get event details
• wegive_list_event_registrations - List registrations
• wegive_get_event_registration - Get registration details

Fundraisers

• wegive_list_fundraisers - List P2P fundraisers
• wegive_get_fundraiser - Get fundraiser details

Funds

• wegive_list_funds - List funds/designations
• wegive_get_fund - Get fund details

Checkouts

• wegive_list_checkouts - List donation forms
• wegive_get_checkout - Get checkout details

Households

• wegive_list_households - List households
• wegive_get_household - Get household details

Communication

• wegive_list_communication_lists - List email lists
• wegive_get_communication_list - Get list details
• wegive_list_messages - List message campaigns
• wegive_get_message - Get message details

Journeys

• wegive_list_journeys - List automated journeys
• wegive_get_journey - Get journey details
• wegive_add_donors_to_journey - Add donors to journey

Tags

• wegive_list_tags - List donor tags
• wegive_get_tag - Get tag details
• wegive_create_tag - Create a tag
• wegive_update_tag - Update a tag

Pledges

• wegive_list_pledges - List pledges
• wegive_get_pledge - Get pledge details

Payouts

• wegive_list_payouts - List payouts
• wegive_get_payout - Get payout details
• wegive_get_financial_reconciliation - Financial report

AI Features

• wegive_ask_ai - Ask AI about your data
• wegive_ai_audience_segment - AI audience segmentation

Virtual Terminal

• wegive_generate_virtual_terminal_url - Generate donation URL

Bulk Actions

• wegive_archive_models - Archive records
• wegive_restore_models - Restore records
• wegive_tag_donors - Bulk tag donors

Product Knowledge

• wegive_knowledge - Query WeGive product knowledge base with persona-appropriate answers

Advanced Filtering

Most list endpoints support advanced filtering options. Each tool's description includes specific filter documentation.

Date Range Filters

Filter by date ranges using _start and _end suffixes with ISO 8601 dates:

created_at_start: "2024-01-01"
created_at_end: "2024-12-31"

Common date fields by entity:

• All entities: created_at, updated_at
• Transactions: completed_at, refunded_at, failed_at
• Recurring: next_donation_at, last_donation_at
• Payouts: paid_at
• Events: start_at, end_at
• Pledges: start_date, end_date
• Messages: sent_at

Sorting

Sort results using a JSON object with field names and directions:

sort: {"created_at": "desc"}
sort: {"amount": "asc", "created_at": "desc"}

Sortable fields by entity:

• Donors: id, name, email, type, total_given, given_ytd, last_donation
• Transactions: id, date, amount, fee, supporter, designation, net_revenue
• Campaigns: id, name, net_revenue, created
• Recurring: id, amount, frequency, next_donation_at, status
• Fundraisers: id, name, creator, goal, raised

Amount Filters

Filter by amount ranges (values in cents):

amount_min: 1000   # $10.00 minimum
amount_max: 10000  # $100.00 maximum

Entity-Specific Filters

Donors (wegive_list_donors):

• type: individual, company, recurring, both
• tag, tags: Filter by tag ID(s)
• campaign, checkout, fund: Filter by related entities
• recurring: true/false - has active recurring gift
• recurring_frequency: monthly, weekly, biweekly, yearly, daily, quarterly
• marketing_contact, do_not_contact: true/false
• has_duplicates: true/false
• last_integration_status: error, processed, ignored, pending

Transactions (wegive_list_transactions):

• type: donation, recurring, service-revenue, both
• status: pending, success, refunded, failed, disputed, processing, retried
• payment_method: card, bank, offline
• payment_processor: tilled, payrix, stripe, wegive, finix
• donor_type: company, individual
• fee_covered: true/false
• in_honor_memory: true/false (tribute gifts)
• is_tax_deductible, anonymous, guest: true/false
• utm_source, utm_medium, utm_campaign: tracking parameters

Recurring Donations (wegive_list_scheduled_donations):

• status: active, paused, cancelled, ended, expiring-soon, ending-soon, in-arrears, missing
• frequency: weekly, biweekly, monthly, quarterly, annually, daily, first_and_15th
• in_dunning: true/false (failed payment retries)

Messages (wegive_list_messages):

• status: draft, scheduled, sending, sent, failed
• type: email, sms

Pledges (wegive_list_pledges):

• status: active, completed, cancelled, overdue

Multiple Values

Filter by multiple values using comma-separated strings:

status: "completed,pending"
fund: "1,2,3"
tag: "major-donor,board-member"

Product Knowledge Tool

The wegive_knowledge tool queries the WeGive product knowledge base. It requires the WEGIVE_KNOWLEDGE_API_KEY environment variable. If you omit persona, the server uses WEGIVE_DEFAULT_PERSONA or defaults to engineering.

Personas

Choose the appropriate persona for your audience:

| Persona | Use Case | |---------|----------| | engineering | Technical details, code locations, implementation specifics (includes source file references) | | cs | Customer support focused answers for helping users | | sales | Feature and capability focused for sales conversations | | customer | End-user friendly explanations | | documentation | Technical writing style for docs |

Examples

"How do recurring donations work?" (persona: cs)
"Where is the donation processing code?" (persona: engineering)
"What payment processors does WeGive support?" (persona: sales)

Example Queries

Once configured, ask Claude things like:

• "Show me the top 10 donors this year"
• "List all active recurring donations"
• "Find donors who gave to the Annual Fund campaign"
• "Get details for donor ID 12345"
• "Generate a virtual terminal URL for the General Fund"
• "List transactions from January 2024 sorted by amount descending"
• "Find recurring donations expiring in the next 30 days"

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

Publishing

npm publish