realnex-mcp

A Model Context Protocol (MCP) server that lets Claude talk to a RealNex CRM in plain English.

This is a monorepo containing two related Python packages:

• realnex_api_client — a thin Python wrapper around the RealNex Sync API (auth, requests, OData query building, retry/backoff). Reusable on its own.
• realnex_mcp_server — wraps the API client and exposes 12 tools to Claude via MCP. The thing end-users actually install.

The intent is that the same realnex_api_client is later reused by realnex-automation-templates (v1.0 — webhook receivers, lead-form pipelines, etc.) so we never have two copies of the API code.

Status

v0.1 — pre-alpha, scaffolding only. See ../realnex_mcp_scoping.md for the architecture and tool plan.

Install (end users)

See docs/install.md for the full walkthrough. Short version:

1. Generate an API token in RealNex: Settings → Admin → User Management → API Token
2. pip install realnex-mcp
3. Add the config block (see examples/claude_desktop_config.json) to your Claude Desktop config and paste your token in
4. Restart Claude. Ask: "who am I logged in as on RealNex?"

The token inherits your user's exact RealNex permissions — if you can't delete a contact in the web UI, the API can't either. Admins can generate tokens on behalf of users who don't have permission to do it themselves.

Local dev

# Recommended: uv (fast Python package manager)
uv venv
uv pip install -e ".[dev]"

# Run the MCP server in stdio mode for testing
python -m realnex_mcp_server

Layout

realnex-mcp/
├── packages/
│   ├── realnex_api_client/       # the foundation lib
│   └── realnex_mcp_server/       # the MCP wrapper
├── examples/
│   ├── claude_desktop_config.json
│   └── example_prompts.md
├── docs/
├── tests/
└── pyproject.toml

License

MIT (open-source; commercial setup/support/customization is the revenue layer).