ngpvan-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| VAN_API_KEY | No | Your VAN API key GUID. |1 (My Campaign) or |0 (My Voters) is added from the config. | |
| VAN_APP_NAME | Yes | Your VAN application name. | |
| VAN_API_KEY_SECRET | No | Google Secret Manager secret name for the VAN API key. | |
| NGPVAN_MCP_HTTP_TOKEN | No | Bearer token required when using the HTTP transport. Generate with openssl rand -hex 32. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Tools for reading one organization's NGP VAN data: people, contact history, events and shifts, saved lists and turf door counts, survey questions and activist codes.
This server never returns phone numbers, emails, street addresses or birth dates. If asked for them, say they aren't available here and suggest the person look in VAN directly.
Names may be shortened to a first name and last initial; use what the tool returns.
Prefer the summary tools. Quote numbers exactly as the tool returned them and name the tool you got them from, e.g. "(turf_door_counts)".
IDs (VAN IDs, event IDs, survey question and response IDs, code IDs) come from tool results. Look them up first (search_people, list_events, list_survey_questions, canvass_codes); never make one up.
If no tool can answer, say so rather than estimating.
Writes are off unless the operator turned one on. When one is on, always run it with dry_run=true first and get the person's OK before sending it.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| check_connectionA | Which VAN committee and database this server is connected to, and which write tools are on. |
| search_peopleA | Find people by name, city or ZIP. Returns VAN IDs, names and cities, plus the total match count. Searching by phone number or email is not offered. |
| get_personA | One person's name, city and what contact info is on file (yes/no and SMS opt-in), never the values. |
| person_activist_codesB | The activist codes applied to one person, with dates. |
| person_signupsB | Every event shift one person has signed up for, with role and status. |
| contact_history_summaryB | Counts of contact attempts for up to 25 people: by contact type (phone, walk, text), by result (canvassed, not home, refused...) and survey responses recorded. |
| list_eventsA | Events starting between two dates (inclusive), with their shifts and locations. |
| event_signups_summaryA | Who is signed up for an event or one of its shifts: counts by status, how many are committed, and the roster (names as the privacy policy allows, role, status). |
| list_foldersB | The saved-list folders this API key can see. |
| turf_door_countsB | Doors and people per saved list (turf) in a folder, with folder totals. With no folder, every folder. |
| list_survey_questionsC | Survey questions with their script and possible responses. |
| list_activist_codesC | Activist codes available in this committee. |
| canvass_codesB | Result codes (Not Home, Refused, Wrong Number...) and contact types (Phone, Walk, SMS). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 13 tools
Most tools target clearly distinct resources: person-level lookups, event-level lookups, folder/turf reporting, and reference-code listings. The closest pair is person_signups (all shifts for one person) versus event_signups_summary (roster for one event/shift), but the descriptions make the direction of the query explicit. Reference lookups (list_activist_codes, list_survey_questions, canvass_codes) are separate but clearly scoped to different data types.
A partial convention exists (list_* for collections, get_/search_ for single-record access, *_summary for aggregates), but noun-phrase names like person_activist_codes, turf_door_counts, and canvass_codes mix with verb-led names, and person_signups vs event_signups_summary is inconsistent in style. Still readable, but an agent cannot rely on a single predictable pattern to guess a tool name.
13 tools is well within a healthy range and each maps to a real read operation on the VAN surface. The only mild redundancy is three separate reference-data tools (activist codes, survey questions, canvass codes) that could plausibly be one metadata call.
The surface covers people, contacts, events, signups, folders/turfs, and code lookups — a coherent read-only slice. However, searching by phone or email is explicitly not offered and contact values are never returned, which are significant gaps for common canvassing workflows, and there are no write operations despite check_connection referencing them.