nb-mcp

MikeOmlor/nb-mcp

3.2

If you are the rightful owner of nb-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

An unofficial Model Context Protocol (MCP) server providing AI assistants with access to NationBuilder's API v2 for community management, fundraising, and engagement.

Tools
5
Resources
0
Prompts
0

NationBuilder MCP Server

An unofficial Model Context Protocol (MCP) server that provides AI assistants with access to NationBuilder's API v2. This server enables secure, controlled access to NationBuilder's community management, fundraising, and engagement tools.

Features

  • ✅ Tags Management: Complete CRUD operations for NationBuilder tags
  • ✅ People Tagging: Assign, remove, and manage tags on people
  • ✅ Advanced Search: Search tags with multiple criteria and filters
  • ✅ Convenience Tools: Popular tags, recent tags, system tags
  • ✅ Basic MCP server framework
  • ✅ NationBuilder API v2 authentication
  • ✅ Health check functionality
  • ✅ People management with advanced filtering (location, demographics, engagement)
  • ✅ Bulk people import/upsert operations
  • 🚧 Donation processing tools (planned)
  • 🚧 Event management tools (planned)
  • 🚧 Communication tools (planned)

API Documentation Gap

⚠️ Important Note: The provided OpenAPI specification does not include tags endpoints, but these endpoints are fully functional in NationBuilder's API v2. See for complete endpoint documentation and confirmed functionality.

Prerequisites

  • Node.js 18+
  • TypeScript 5+
  • A NationBuilder account with API v2 access
  • NationBuilder API v2 token

Installation

Quick Start

  1. Install the MCP server from npm

    npm install -g nb-mcp-server

  2. Run the interactive setup wizard

    nb-mcp-setup

    The wizard will:

    • Prompt for your NationBuilder API v2 token
    • Ask for your nation slug (e.g., 'myorg' from myorg.nationbuilder.com)
    • Validate your credentials
    • Securely encrypt and save your configuration to ~/.nb-mcp/config.json

  3. Configure Claude Desktop (or other MCP client)

    Edit your Claude Desktop configuration file:

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

    Add the NationBuilder MCP server:

    {
  "mcpServers": {
    "nationbuilder": {
      "command": "nb-mcp-server"
    }
  }
}

  4. Restart Claude Desktop

    Your NationBuilder MCP server is now available! You can verify by asking Claude to run a health check or search for people.

Alternative Installation Methods

Using CLI arguments instead of setup wizard:

nb-mcp-server --token "your_api_token" --nation "your_nation_slug"

Using environment variables:

export NATIONBUILDER_API_TOKEN="your_api_token"
export NATIONBUILDER_NATION_SLUG="myorg"
nb-mcp-server

Local development:

git clone <repository-url>
cd nb-mcp-server
npm install
npm run build
npm run setup  # or: node dist/server.js --token "..." --nation "..."

Interactive Setup Wizard

The setup wizard provides the easiest way to configure your NationBuilder MCP Server:

$ nb-mcp-setup
┌─────────────────────────────────────────────────┐
│  🏛️  NationBuilder MCP Server Setup Wizard     │
└─────────────────────────────────────────────────┘

Welcome! Let's configure your NationBuilder MCP Server.

? Enter your NationBuilder API v2 token: [hidden input]
? Enter your nation slug (e.g., 'myorg' from myorg.nationbuilder.com): myorg
? API Base URL (leave blank for default): [https://api.nationbuilder.com]

✓ Validating credentials...
✓ Connection successful!
✓ Found nation: "My Organization"
✓ API access confirmed

? Save credentials securely for future use? (Y/n) Y

✅ Setup complete!
Your credentials are saved and encrypted.
You can now run: nb-mcp-server

Setup Wizard Commands

nb-mcp-setup              # Run interactive setup
nb-mcp-setup --reset      # Reset/reconfigure existing setup
nb-mcp-setup --show       # Show current configuration (masked)
nb-mcp-setup --clear      # Clear saved configuration
nb-mcp-setup --help       # Show help information

Security Features

  • 🔒 Encrypted Storage: Credentials are encrypted using Node.js crypto
  • 🏠 Local Storage: Saved to ~/.nb-mcp/config.json
  • ✅ Validation: API credentials tested during setup
  • 🔄 Easy Reset: Simple commands to reconfigure

Get Your NationBuilder API Token

  1. Log into your NationBuilder control panel
  2. Go to Settings → Developer → API
  3. Generate a new API v2 token
  4. Use with setup wizard, CLI flags, or environment variables

Usage

CLI Options

nb-mcp-server [options]

Options:
  -t, --token <token>    NationBuilder API v2 token
  -n, --nation <slug>    NationBuilder nation slug (e.g., 'myorg' from myorg.nationbuilder.com)
  -u, --url <url>        NationBuilder API base URL (default: https://api.nationbuilder.com)
  -v, --verbose          Enable verbose logging
  -h, --help             Display help information
  --version              Display version number

Examples

# Basic usage with required parameters
nb-mcp-server --token "your_api_token" --nation "myorg"

# With verbose logging
nb-mcp-server --token "your_api_token" --nation "myorg" --verbose

# Using environment variables
export NATIONBUILDER_API_TOKEN="your_api_token"
export NATIONBUILDER_NATION_SLUG="myorg"
nb-mcp-server

# Mix environment and CLI (CLI overrides environment)
export NATIONBUILDER_API_TOKEN="your_api_token"
nb-mcp-server --nation "myorg"

Usage with MCP Clients

Claude Desktop

Add this server to your Claude Desktop configuration:

Option 1: Using setup wizard (easiest)

{
  "mcpServers": {
    "nationbuilder": {
      "command": "nb-mcp-server"
    }
  }
}

Option 2: Using CLI arguments

{
  "mcpServers": {
    "nationbuilder": {
      "command": "nb-mcp-server",
      "args": ["--token", "your_api_token", "--nation", "your_nation_slug"]
    }
  }
}

Option 2: Using environment variables

{
  "mcpServers": {
    "nationbuilder": {
      "command": "nb-mcp-server",
      "env": {
        "NATIONBUILDER_API_TOKEN": "your_api_token",
        "NATIONBUILDER_NATION_SLUG": "your_nation_slug"
      }
    }
  }
}

Option 3: Local development

{
  "mcpServers": {
    "nationbuilder": {
      "command": "node",
      "args": ["/path/to/nb-mcp-server/dist/server.js", "--token", "your_api_token", "--nation", "your_nation_slug"]
    }
  }
}

Other MCP Clients

This server implements the standard MCP protocol and should work with any MCP-compatible client using stdio transport.

Available Tools

People Management Tools

  • search_signups - Search for people with advanced filtering options including:
    • Basic filters: Name, email, phone, party affiliation
    • Advanced email filtering: Exact match, prefix, suffix, contains with include/exclude options
    • Demographics: Support level (0-5), created/updated dates
    • Location-based search: Find people within a radius of a specific location (latitude/longitude)
    • Engagement: Filter by tags, signup page, bounced email status
    • Sideloading: Include relationships (tags, recruiter, voter data) and extra fields (addresses)
    • Pagination & sorting: Flexible result navigation
  • get_signup - Retrieve detailed information for a specific person
  • create_signup - Add a new person to the database
  • update_signup - Modify person information and tags
  • delete_signup - Remove a person (cannot be undone)
  • push_signups - Bulk import/upsert multiple people (up to 100 at once)
  • get_me - Get your own profile information
  • list_signups_by_list - Get all people from a specific list
Location-Based Search Example

Find people near San Francisco within 10 miles:

nearby_location: "37.7749,-122.4194"
nearby_distance: 10
Advanced Email Filtering Example

Find emails ending with "@example.com":

email_operator: "suffix"
email_value: "@example.com"

📖 For comprehensive filtering documentation and examples, see

Tags Management Tools

  • search_tags - Search and filter tags with various criteria
  • get_tag - Get detailed tag information by ID or name
  • create_tag - Create new tags with optional color and description
  • update_tag - Update existing tag properties
  • delete_tag - Delete tags (cannot be undone)
  • assign_tags - Assign/remove/replace tags on people
  • get_people_by_tag - List people with specific tags

Convenience Tools

  • popular_tags - Get most popular tags by usage count
  • recent_tags - Get recently created tags
  • system_tags - List system-defined tags

System Tools

  • health_check - Verify server configuration and connectivity

Planned Tools

  • search_donations - Query donation records
  • process_donation - Create new donation records
  • list_events - Get upcoming/past events
  • manage_rsvps - Handle event registrations

Development

Project Structure

nb-mcp/
├── src/
│   ├── server.ts           # Main MCP server
│   ├── nationbuilder/      # NationBuilder API integration
│   ├── tools/             # MCP tool implementations
│   └── utils/             # Utilities and configuration
├── dist/                  # Compiled JavaScript
└── docs/                  # Documentation

Scripts

  • npm run dev - Start development server with auto-reload
  • npm run build - Compile TypeScript to JavaScript
  • npm start - Run compiled server
  • npm test - Run tests (when available)

Contributing

This is an early-stage project. Contributions are welcome!

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests
  5. Submit a pull request

API Compatibility

This server integrates with NationBuilder's API v2, which:

  • Follows JSON:API spec v1.0
  • Supports advanced filtering, sorting, and pagination
  • Includes sideloading and sideposting capabilities
  • Requires valid API v2 tokens

Security

  • API tokens are securely handled and never logged
  • All communication uses HTTPS
  • Server follows MCP security best practices
  • Logs are written to stderr (required for MCP stdio transport)

License

ISC License - see LICENSE file for details

Support

This is an unofficial, community-maintained project. For:

  • NationBuilder API issues: Contact NationBuilder support
  • MCP Server issues: Open an issue in this repository
  • Feature requests: Open an issue with the "enhancement" label

Note: This server is not affiliated with or endorsed by NationBuilder. It is a community project that uses NationBuilder's public API.