DealMachine MCP server

DealMachine CLI

Maintainers: agent instructions, development, current Command reference, and npm releases.

DealMachine CLI (dm) -- property intelligence from the command line.

A standalone Commander.js CLI that talks to the DealMachine REST API. Provides Commands for authentication, property and people research, enrichment, lists, prospects, tags, webhooks, mail and developer utilities. Compiles to ESM JavaScript via tsc.

This package has zero @dealmachine/* dependencies -- it is a self-contained binary that communicates exclusively through the public API.

---

AI agent integrations

This repository is also the public distribution package for the DealMachine MCP server and DealMachine skill.

• Hosted MCP server: https://mcp.dealmachine.com
• API documentation: https://api.docs.dealmachine.com
• Account and API keys: https://dealmachine.com/settings/developer
• Privacy policy: https://dealmachine.com/privacy-policy
• Terms of service: https://dealmachine.com/terms-of-service
• Support: support@dealmachine.com

The MCP server supports OAuth 2.1 for ChatGPT, Claude, Cursor, Codex, and other compatible clients. It can also use a DealMachine API key in developer clients that support bearer-token configuration.

The plugin package includes:

• A hosted MCP connection for property, people, enrichment, comparable-sales, and account tools
• A credit-aware skill that discovers filters and fields, counts first, and confirms large paid operations
• A portable Agent Plugins package for compatible clients
• Manifests for OpenAI, Claude, Cursor, GitHub Copilot, and Gemini
• Official MCP Registry metadata in server.json

The portable package follows Agent Plugins 1.0.0:

dealmachine-cli/
├── plugin.json
├── mcp.json
└── skills/
    └── dealmachine/
        ├── SKILL.md
        ├── REFERENCE.md
        └── SETUP.md

Compatible clients discover the DealMachine skill from skills/dealmachine/ and connect to the hosted Streamable HTTP MCP server declared in mcp.json. Client-specific manifests remain in the repository for compatibility, marketplace metadata, and richer presentation.

Example requests:

• "Find high-equity absentee-owned properties in Austin and estimate the credit cost first."
• "Look up the owner of this property and find available contact data."
• "Find comparable sales for this property."
• "Research people who match these criteria for a targeted prospecting list."

Direct skill installation:

npx skills add DealMachine/dealmachine-cli

---

Table of Contents

• AI agent integrations
• Installation
• Authentication
• Configuration
• Commands
  • Agents -- agents, agents guide, agents playbook, agents install, agents permissions
  • Auth -- login, logout, whoami
  • Config -- config get, config set, config path
  • Account -- account
  • Usage -- usage
  • Properties -- search, count, get, ids, export
  • People -- search, count, get, ids, export
  • Enrich -- address, latlng, apn, email, phone, name
  • Comps -- comparable property analysis
  • Lists -- search, create, get, update, delete, build, import, items, add, remove, export
  • Filters -- list available search filters
  • Fields -- list available data fields
  • Activity -- search, get
  • Addresses -- autocomplete, validate
  • Dev -- license add, license list, license remove
• Global Options
• Input Methods
• Project Structure
• Building
• Adding New Commands
• Dependencies

---

Installation

From npm (global)

npm install -g dealmachine
dm login

The canonical implementation package is @dealmachine/cli. The dealmachine package is the short install alias and provides the same dm command.

From source

cd dealmachine-cli
npm run build
node dist/index.js whoami

Link for local development

cd dealmachine-cli
npm link
dm --version

The binary entry is dist/index.js, declared in package.json under bin.dm. Requires Node.js >= 18.

---

Authentication

The CLI supports two authentication methods.

Device Auth Flow (RFC 8628)

The default dm login command uses the OAuth 2.0 Device Authorization Grant (RFC 8628). This is the recommended flow for interactive use:

dm login

1. The CLI requests a device code from POST /v1/auth/device/code with client ID dealmachine-next-cli and your machine's hostname.
2. A verification URL and user code are displayed. The browser opens automatically (unless --no-browser).
3. You authorize the device in the browser by entering the user code.
4. The CLI polls POST /v1/auth/device/token at the server-specified interval.
5. On success, the API key, key ID, and organization details are stored to ~/.dealmachine/config.json.

The polling handles all RFC 8628 responses: authorization_pending, slow_down (backs off by 5s), access_denied, and expired_token.

# Skip auto-opening the browser
dm login --no-browser

# Target a specific environment
dm login --env local
dm login --env staging

Direct API Key Login

For CI pipelines, scripts, or local development, pass an API key directly:

dm login --key dm_sk_live_abc123...

The key is verified against GET /v1/account before being stored. If verification fails, the CLI exits with a non-zero code.

If you do not have an API key yet, use dm signup <email> --login or dm login. Free accounts can count matches and estimate costs before paying. Public plan checkout only accepts self-serve Basic and Pro prices from the shared plan catalog and is capped at 60,000 monthly data credits.

Switching Environments

If you are already logged in, you can switch the target API environment without logging out:

dm login --env local       # Switch to http://localhost:3001/v1
dm login --env staging     # Switch to https://api-staging.v2.dealmachine.com/v1
dm login --env production  # Switch to https://api.v2.dealmachine.com/v1

Logout

dm logout

Removes the config file at ~/.dealmachine/config.json.

---

Configuration

Credentials are stored at ~/.dealmachine/config.json with file permissions 0600 (owner read/write only). The config directory ~/.dealmachine/ is created with mode 0700.

Config File Schema

{
  "apiKey": "dm_sk_live_...",
  "keyId": "key_abc123",
  "organizationId": 42,
  "organizationName": "Acme Corp",
  "organizationSlug": "acme-corp",
  "apiEnvironment": "production"
}

Environment Variables

The CLI checks these environment variables for API URL resolution (in priority order):

Variable	Purpose	Example
DM_API_URL / DEALMACHINE_API_URL	Direct URL override	http://localhost:3001/v1
DM_ENV / DEALMACHINE_ENVIRONMENT	Environment name	local, staging, or production

If none are set, the CLI falls back to the apiEnvironment field in the config file, then defaults to production.

API Environments

Environment	URL
local	http://localhost:3001/v1
staging	https://api-staging.v2.dealmachine.com/v1
production	https://api.v2.dealmachine.com/v1

---

Commands

Agents Commands

dm agents

Print concise guidance for agents using the CLI. This is the recommended first command when an agent has access to dm but has not loaded the DealMachine Playbook yet.

dm agents
dm agents --json

The guide tells agents to use --json and --quiet, verify auth, fetch live filters and fields before searches, count before credit-consuming work, and confirm expected credit usage before fetching records or exporting.

dm agents guide

Print the same concise agent guidance explicitly.

dm agents guide
dm agents guide --json

dm agents playbook

Print the bundled DealMachine Playbook Markdown. Agents should load this before translating natural language property, people, contact, enrichment, list, export, comps, or credit-usage requests into CLI commands.

dm agents playbook
dm agents playbook --json
dm agents skill        # alias

The public CLI source keeps its bundled Playbook at playbook/PLAYBOOK.md. The build writes the selected source to dist/agents/dealmachine-playbook.md, so the command works from a published CLI package as well as a local source checkout.

dm agents install claude-code

Install the Playbook as a native Claude Code skill. Personal scope is the default. Project scope installs under the current repository.

dm agents install claude-code
dm agents install claude-code --project

dm agents permissions

Print the narrow Claude Code allowlist for free discovery and count commands. Paid and mutating commands are not pre-approved.

dm agents permissions
dm agents permissions --json

---

Auth Commands

dm signup

Create a public API account and receive an API key. With --login, the credential is saved locally and omitted from output (including JSON); use this form from an agent:

dm signup developer@example.com --first-name Ada --last-name Lovelace --phone-number +15551234567
dm signup developer@example.com --login

dm plans

List live self-serve plans, included credits, features and free API access. Connected customers receive their workspace prices:

dm plans
dm plans --json

dm checkout

Preview the recurring terms using a current price ID from dm plans. After the customer approves the exact price, billing interval and quantity, add --yes to create the Stripe checkout link:

dm checkout --price-id price_xxx_monthly --quantity 1 --json
# Only after approval:
dm checkout --price-id price_xxx_monthly --quantity 1 --yes --json

Payment is completed on Stripe. Creating checkout does not activate a plan; check dm account --json and dm usage after payment before retrying enrichment. Counts do not award credits. Free operations still require authentication and obey permissions and rate limits.

dm login

Authenticate with your DealMachine account.

dm login                            # Device auth flow (opens browser)
dm login --no-browser               # Device auth, manual code entry
dm login --key dm_sk_live_abc123    # Direct API key
dm login --env local                # Target local API

Option	Description
--no-browser	Do not automatically open the browser
--key <api-key>	Login directly with an API key (skips browser)
--env <environment>	API environment: local, staging, or production

dm logout

Remove stored credentials.

dm logout

dm whoami

Show current authentication status.

dm whoami               # Show stored credentials
dm whoami --verify      # Verify credentials against the API

Option	Description
--verify	Verify credentials with the API

---

Config Commands

dm config get [key]

Get a configuration value, or display all values when no key is given.

dm config get                   # Show all config values
dm config get apiEnvironment    # Show specific value
dm config get apiKey            # Shows truncated key (first 20 chars)

Available keys: organizationName, organizationSlug, organizationId, apiEnvironment, keyId, apiKey.

dm config set <key> <value>

Set a configuration value. Only apiEnvironment is editable.

dm config set apiEnvironment local
dm config set apiEnvironment staging
dm config set apiEnvironment production

dm config path

Print the absolute path to the config file.

dm config path
# /Users/you/.dealmachine/config.json

---

Account Commands

dm account

Display account information including organization name, ID, creation date, and auth type.

dm account

Output:

Account
────────────────────────────────────────
Organization:  Acme Corp
Org ID:        42
Created:       Jan 15, 2025
Auth Type:     api_key

---

Usage Commands

dm usage

Show credit usage for the current billing cycle.

dm usage           # Human-readable table
dm usage --json    # Machine-readable JSON

Output:

Credit Usage
──────────────────────────────────────────────────
  Plan:         Pro
  Cycle:        Mar 1, 2026 : Mar 31, 2026

  Credits:      4,200 / 10,000 (42%)
  Remaining:    5,800

  Breakdown:
    Properties: 3,100
    People:     1,100

---

Properties Commands

dm properties search

Search properties with filters and locations.

# Inline JSON body
dm properties search --body '{
  "locations": [{"type": "zip_code", "code": "78704"}],
  "filters": [{"filter_id": "property_type", "operator": "is_any_of", "value": ["single_family"]}]
}'

# From a file
dm properties search -f search.json

# Pipe from stdin
cat search.json | dm properties search

# Machine-readable output
dm properties search -f search.json --json              # Free estimate for scripts and agents
dm properties search -f search.json --json --yes        # Run after approval

# Explicit free estimate
dm properties search -f search.json --estimate-cost

# Query Builder protocol filters
dm properties search --include-lists 123,456 --exclude-previously-exported --body '{"locations":[]}'

Option	Description
--body <json>	Request body as JSON string
-f, --file <path>	Read request body from a JSON file
--include-lists <ids>	Comma-separated list IDs to include
--exclude-lists <ids>	Comma-separated list IDs to exclude
--exclude-previously-exported	Exclude records already exported by your organization
--bigquery-data-environment <n>	Query Builder data environment (1 production, 2 staging, 3 development)
--estimate-cost	Preview counts and credit cost without consuming credits
--yes	Confirm approved credit spend for non-interactive execution
--json	Output as JSON

dm properties count

Count properties matching filters without consuming credits.

dm properties count --body '{"locations": [{"type": "state", "code": "TX"}]}'
dm properties count -f filters.json --json

dm properties get <id>

Get a single property by its DealMachine ID.

dm properties get prop_12345
dm properties get prop_12345 --contact-audience owners_and_family
dm properties get prop_12345 --contact-audience none
dm properties get prop_12345 --fields estimated_value,equity
dm properties get prop_12345 --json

Option	Description
--contact-audience <audience>	owners, owners_and_family, renters, residents, all, none
--fields <csv>	Comma-separated property field IDs from dm fields
--json	Output as JSON

Property lookup defaults to owners. If you only need property data, use --contact-audience none. This omits contacts and avoids people credits.

dm properties ids [ids...]

Get multiple properties by their IDs in a single batch request.

# Positional arguments
dm properties ids prop_111 prop_222 prop_333

# Via JSON body
dm properties ids --body '{"ids": ["prop_111", "prop_222"]}'

# From file
dm properties ids -f ids.json --contact-audience owners
dm properties ids -f ids.json --contact-audience none

Option	Description
--body <json>	Request body as JSON string
-f, --file <path>	Read request body from a JSON file
--contact-audience <audience>	Include contacts: owners, owners_and_family, renters, residents, all, none
--json	Output as JSON

dm properties export

Export properties as CSV (up to 1,000,000 records). Returns signed download URLs.

dm properties export -f search.json
dm properties export -f search.json --require-phone --scrub-dnc
dm properties export --body '{"locations": [...]}' --mobile-only --json

Option	Description
--body <json>	Request body as JSON string
-f, --file <path>	Read request body from a JSON file
--require-phone	Only include records where the contact has a phone number
--require-email	Only include records where the contact has an email address
--mobile-only	Only include wireless phone numbers
--landline-only	Only include landline phone numbers
--scrub-dnc	Exclude contacts on the Do Not Call registry
--json	Output as JSON

---

People Commands

dm people search

Search people with filters and locations.

dm people search --body '{
  "locations": [{"type": "zip_code", "code": "78704"}],
  "filters": [{"filter_id": "age", "operator": "between", "value": [30, 50]}]
}'
dm people search -f people-search.json --json
dm people search -f people-search.json --estimate-cost
dm people search -f people-search.json --json --yes
dm people search --include-lists 123 --exclude-lists 456 --exclude-previously-exported --body '{"locations":[]}'

Non-interactive People Search returns a free estimate unless --yes is supplied. A specific person by name uses dm enrich name, not People Search.

dm people count

Count people matching filters without consuming credits.

dm people count -f filters.json

dm people get <id>

Get a single person by their DealMachine ID.

dm people get per_12345
dm people get per_12345 --include-properties --property-limit 20
dm people get per_12345 --fields estimated_household_income,estimated_value
dm people get per_12345 --json

Option	Description
--include-properties	Include associated properties
--property-limit <n>	Maximum associated properties to return, from 1 through 100
--fields <csv>	Comma-separated field IDs from dm fields
--json	Output as JSON

dm people ids [ids...]

Get multiple people by their IDs in a single batch request.

dm people ids per_111 per_222 per_333
dm people ids --body '{"ids": ["per_111", "per_222"]}' --include-properties --property-limit 20
dm people ids per_111 per_222 --fields estimated_household_income,estimated_value

Option	Description
--include-properties	Include associated properties
--property-limit <n>	Maximum associated properties to return per person, up to 100
--fields <csv>	Comma-separated field IDs from dm fields

dm people export

Export people as CSV (up to 1,000,000 records). Returns signed download URLs.

dm people export -f search.json --require-email
dm people export -f search.json --mobile-only --scrub-dnc --json

Contact filter options are the same as dm properties export.

---

Enrich Commands

All enrichment commands support three input modes: a positional argument for single-item lookup, --body/-f for JSON payloads, and -f with a .csv file for batch enrichment from CSV. Batches larger than 250 items are automatically chunked. Every enrichment command accepts --fields <csv> and sends the selected field IDs to the API. Email, phone, and name matches also include a free property_count; use --include-properties when you need the property records themselves.

dm enrich address [address]

Look up a property by street address.

# Single address
dm enrich address "123 Main St, Austin, TX 78704"
dm enrich address "123 Main St, Austin, TX 78704" --contact-audience none
dm enrich address "123 Main St, Austin, TX 78704" --fields estimated_value,equity

# Batch from JSON
dm enrich address --body '{"data": [{"full_address": "123 Main St, Austin, TX"}]}'

# Batch from CSV (auto-detected by .csv extension)
dm enrich address -f addresses.csv --contact-audience owners

# CSV columns: full_address (or street, city, state, zip)

Option	Description
--body <json>	Request body as JSON string
-f, --file <path>	Read from JSON or CSV file
--contact-audience <audience>	owners, owners_and_family, renters, residents, none
--fields <csv>	Comma-separated field IDs from dm fields
--json	Output as JSON

Use --contact-audience none whenever you only need the property. The response omits contacts and consumes zero people credits.