virtuous-mcp

Virtuous CRM+ MCP Server

An MCP server, built with FastMCP, that lets an AI assistant work with Virtuous CRM+: query and read data freely, and—only with explicit user confirmation—create, update, archive, or delete data.

It provides complete coverage of the entire Virtuous API (all 291 endpoints across 39 resource groups) through a small set of convenience tools plus a generic discovery + call layer, so any endpoint can be reached without needing a separate tool per endpoint.

Safety model: reads are free, writes require confirmation

Reading (querying, searching, looking up, listing reference data) runs freely.

Every tool that changes data is "mutating" and is guarded in three layers:

1. Instructions — the server and each mutating tool tell the model it must

describe the exact change and get explicit user approval before acting.

1. confirm flag — every mutating tool takes confirm (default false).

With confirm=false the tool makes no API call and returns a preview of what it would do, so the model can show the user and ask.

1. Client backstop — the HTTP client raises ConfirmationRequired if a

write is ever attempted without explicit confirmation, so an accidental confirm=true is the only way a write can happen.

A request is classified as a read if it's a GET, or a POST to a /Query, /QueryOptions, /Search, /Find, or /Proximity path. Everything else is a write.

Operational protocols

The HTTP layer is aligned with Virtuous's documented operational behavior:

• Connection pooling — a single httpx.AsyncClient is reused for the life

of the process (per base URL), so TLS/keep-alive connections are reused instead of re-established on every call.

• Rate limits — Virtuous enforces an org-wide budget (documented at

5,000 requests/hour) shared by every API key/integration in the org, and returns X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset on every response. The client records the latest values; call get_rate_limit_status to inspect remaining budget.

• Retries + backoff — transient 429 and 5xx responses are retried (up to

3 times). 429 waits honor Retry-After / X-RateLimit-Reset; otherwise an exponential backoff with jitter is used.

• Pagination — query endpoints cap at 1000 records/call; query_all

auto-pages (with a hard ceiling) so you don't manually loop skip/take.

• Bulk writes — create_batch posts many contacts/gifts in one request via

the recommended batch endpoints, conserving the shared rate budget.

Tools

Full-API discovery + generic call

The entire API is reachable through these. Use discovery to find the exact method + path, then call_endpoint to invoke it.

| Tool | Purpose | | --- | --- | | list_resources() | List all 39 resource groups and their read/write endpoint counts. | | list_endpoints(resource, search, only) | Discover any endpoint (filter by resource, text search, or reads/writes). | | describe_endpoint(method, path) | Full metadata + parameters for one endpoint. | | call_endpoint(method, path, path_params, query_params, body, confirm) | Invoke any endpoint. Reads run freely; writes obey the confirmation gate. |

call_endpoint resolves :placeholders in the path from path_params (e.g. /api/Contact/:contactId + {"contactId": 123}), and works even for endpoints not in the bundled registry.

Read tools (no confirmation)

| Tool | Purpose | | --- | --- | | list_query_object_types | List queryable object types + reference-data keys. | | get_query_options(object_type) | Discover queryable fields, data types, and allowed operators for an object. | | query_records(object_type, groups, sort_by, descending, skip, take, full_detail) | Run a filtered bulk query (single page). | | query_all(object_type, groups, sort_by, descending, max_records, page_size, full_detail) | Auto-paginate a query up to max_records (caps pages; reports rate-limit budget). | | get_record(object_type, record_id) | Fetch a single record by id. | | find_contact(email \| reference_source+reference_id) | Look up one contact. | | search_contacts(search, skip, take) | Fuzzy free-text contact search. | | get_gifts_by_contact(contact_id) | All gifts for a contact. | | get_contact_notes(contact_id, important_only) | Notes for a contact. | | get_individuals_by_contact(contact_id) | Individuals that make up a contact. | | get_reference_data(key) | Lookup lists: contact/gift/project/task types, tags, custom fields, org groups, etc. | | get_current_context() | Current organization + the API key's permissions. | | get_rate_limit_status() | Latest observed rate-limit headers (remaining org-wide budget + reset time). | | read_request(path, params) | Escape hatch for arbitrary read-only GET calls. | | read_paged_request(path, params, max_records, page_size) | Auto-page read-only GET endpoints that use skip/take and return a list/total envelope. |

Write tools (MUTATING — require confirm=true after explicit user approval)

| Tool | Purpose | | --- | --- | | create_transaction(kind, body, confirm) | Recommended way to import a single Contact or Gift (matched/validated). | | create_batch(kind, body, confirm) | Bulk-import many Contacts or Gifts in one request (rate-limit-friendly). | | create_record(object_type, body, confirm) | Create a record (e.g. ContactNote, ContactTag, Task, Relationship). | | update_record(object_type, record_id, body, confirm) | Update a record (PUT). | | archive_record(object_type, record_id, unarchive, confirm) | Archive/unarchive a record. | | delete_record(object_type, record_id, confirm) | Destructive delete. | | write_request(method, path, body, confirm) | Escape hatch for any other write (cancel recurring gift, write off pledge, send email, toggle webhook, etc.). |

With confirm omitted/false, write tools (and call_endpoint on a write endpoint) return a confirmation_required preview and change nothing.

Note: call_endpoint is the universal way to reach any write endpoint and is subject to the same confirmation gate. The dedicated write tools above are just ergonomic shortcuts for the most common operations.

How queries work

A query body is made of groups. Conditions within a group are AND-ed; separate groups are OR-ed. Each condition is:

{ "parameter": "<field name>", "operator": "<operator>", "value": "<value>" }

Use get_query_options to get the exact parameter and operator strings for an object. Example: contacts created on/after 2024-01-01, sorted by id desc:

{
  "object_type": "Contact",
  "groups": [
    { "conditions": [
      { "parameter": "Create Date", "operator": "GreaterThanOrEqual", "value": "01/01/2024" }
    ] }
  ],
  "sort_by": "Id",
  "descending": true,
  "take": 100
}

Query endpoints return at most 1000 records per call; use skip/take to page manually, or query_all to auto-paginate up to a max_records ceiling. For non-query GET endpoints that expose the same skip/take pattern (for example contacts by tag or organization-group members), use read_paged_request.

Tasks & reminders (non-obvious gotchas)

These are surfaced at runtime via describe_endpoint (notes + body_params) and in the server instructions, but documented here too:

• Create a task with POST /api/Task. The assignee field is ownerEmail

(the user's email) — not owner, ownerId, or assignedTo. A wrong key is silently ignored and the task is created unassigned, and the success response does not echo ownerEmail back (its absence is not a failure).

• Tasks have no update or delete endpoint. To remove/resolve a task, use the

Reminder endpoints: PUT /api/Reminder/Dismissed/{id} (dismiss ≈ delete) or PUT /api/Reminder/Completed/{id} (mark resolved). There is no un-dismiss / reactivate endpoint via the API (UI only).

• To check if tasks are dismissed/resolved, query Task with the Resolved

filter (IsTrue = dismissed/completed, IsFalse = active). The query result does not expose the owner or an explicit resolved field; the Assigned User filter expects an internal user id (not an email), and no users-list endpoint is exposed.

Setup

1. Get a Virtuous API key: in Virtuous, **Settings → All Settings →

Connectivity → Application Keys → Create an Application Key**.

1. Copy .env.example to .env and set VIRTUOUS_API_KEY.

Install uv

This project is managed with uv, a fast Python package and project manager. Install it once in your environment:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv is also available via other package managers if you prefer:

# Homebrew (macOS)
brew install uv

# pipx
pipx install uv

After installing, restart your shell (or follow the printed instructions) so the uv command is on your PATH, then verify:

uv --version

uv manages the virtual environment and can even provision a compatible Python (3.10+) for you, so you don't need to set up Python separately.

Install dependencies

uv sync

This creates a virtual environment and installs the exact dependencies pinned in uv.lock.

Run

VIRTUOUS_API_KEY=your_key uv run virtuous-mcp

The server speaks MCP over stdio.

Use with an MCP client

Every client below uses the same server entry — only the file it lives in (and the surrounding scope) changes:

{
  "mcpServers": {
    "virtuous-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/cole.j.cantu/Programs/custom-mcp/virtuous-mcp", "virtuous-mcp"],
      "env": { "VIRTUOUS_API_KEY": "your_api_key_here" }
    }
  }
}

Cursor (global / all projects)

Add it to your global Cursor config so it's available in every project:

• macOS / Linux: ~/.cursor/mcp.json
• Windows: %USERPROFILE%\.cursor\mcp.json

Create the file if it doesn't exist and paste the JSON block above (top-level mcpServers key). For a single project instead, use .cursor/mcp.json in that project's root — project config takes precedence over global if both define a server with the same name. Reload Cursor (or toggle the server in Settings → Tools & Integrations → MCP) after saving.

Claude Code (user scope / all projects)

User scope makes the server available to you across all projects. Two ways:

CLI (recommended):

claude mcp add virtuous-mcp \
  --scope user \
  --env VIRTUOUS_API_KEY=your_api_key_here \
  -- uv run --directory /Users/cole.j.cantu/Programs/custom-mcp/virtuous-mcp virtuous-mcp

--scope user writes to ~/.claude.json under the top-level mcpServers key. (Other scopes: project → .mcp.json in the repo root, shared with everyone who clones it; local (default) → your private entry for the current project only.) Everything after -- is the command Claude Code runs to launch the server.

Edit ~/.claude.json directly:

Add the server under the top-level mcpServers object (this is what makes it user-scoped — not nested under a specific project's entry):

{
  "mcpServers": {
    "virtuous-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/Users/cole.j.cantu/Programs/custom-mcp/virtuous-mcp", "virtuous-mcp"],
      "env": { "VIRTUOUS_API_KEY": "your_api_key_here" }
    }
  }
}

~/.claude.json also holds other Claude Code settings, so merge into the existing mcpServers object rather than overwriting the file. Restart your Claude Code session afterward so it re-reads the config.

Claude Code scope reference

| Scope | Where it's stored | Available to | | --- | --- | --- | | local (default) | ~/.claude.json, under this project's entry | You, this project only | | project | .mcp.json in project root | Anyone who clones the repo | | user | ~/.claude.json, top-level mcpServers | You, all projects |

Claude Desktop

Same JSON block in Claude Desktop's claude_desktop_config.json (under mcpServers).

Configuration

| Env var | Required | Default | Description | | --- | --- | --- | --- | | VIRTUOUS_API_KEY | yes | — | Bearer API key / Application Key. | | VIRTUOUS_BASE_URL | no | https://api.virtuoussoftware.com | API base URL. |