livespace-crm-mcp

# Livespace CRM MCP Server

Unofficial [MCP](https://modelcontextprotocol.io) server for
[Livespace CRM](https://www.livespace.io). It exposes 11 intent-shaped tools
instead of mirroring the raw API and targets the stateless Streamable HTTP
transport in MCP spec 2026-07-28.

Version 0.1.2 is available on
[npm](https://www.npmjs.com/package/livespace-crm-mcp/v/0.1.2), in the
[official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.proAutomator%2Flivespace-crm-mcp/versions/0.1.2),
and as a [GitHub Release](https://github.com/proAutomator/livespace-crm-mcp/releases/tag/v0.1.2).

The v1 implementation is complete in this repository. It has six read tools
and five optional write tools, read-only defaults, bounded API access,
sanitized errors and an elicitation-first confirmation flow. Use a test
Livespace account while evaluating it.

## Why this shape?

Livespace's RPC API has about 80 methods, but it does not provide sorting,
aggregation or a direct operation for setting a deal stage. The server groups
those lower-level calls into tasks an MCP client can use safely:

- discovery before IDs are used;
- bounded search, record reads and analysis;
- batch previews before writes;
- per-item outcomes and post-write checks;
- explicit handling of Livespace-specific stage moves and notifications.

## Tools

| Tool | Mode | Purpose and bound |
|---|---|---|
| `health` | Read | Checks the server; `checkLivespace: true` also makes one lightweight Livespace API call. |
| `crm_metadata` | Read | Returns nine dictionary sections, including processes, users, groups, sources, task dictionaries, products and the current user. Optional `userQuery` filters users by name or email before the 500-row cap. |
| `search_crm` | Read | Finds persons, companies or deals, with record links even in lightweight results. Sorted deal searches use one 200-record sort window and report truncation. |
| `get_records` | Read | Reads one record kind and up to 25 ids; walls for at most 5 persons, companies or deals. |
| `get_activity` | Read | Reads one record wall, one bounded CRM feed range or bounded task pages per call. |
| `analyze` | Read | Runs one named aggregation over bounded windows and reports whether its source window was truncated. |
| `create_records` | Write | Creates persons, companies, deals or tasks. Up to 10 items per call, with exact-match contact deduplication by default. |
| `update_records` | Write | Updates persons, companies, deals or tasks. Up to 10 items per call. |
| `log_activities` | Write | Adds public notes or phone calls. Up to 15 notes or calls per call. |
| `move_deals_to_stage` | Write | Moves deals by applying the minimal process-step diff. Up to 10 items per call; backward moves need an explicit allowlist. |
| `notify_user` | Write | Dispatches one in-app notification, limited to 5 per 10 minutes and 1 per recipient per minute. |

`move_deals_to_stage` works by checking and unchecking process steps because
Livespace has no "set stage" call. A deal stands at its furthest checked step.
A backward move therefore unchecks completed steps and can change the
historical meaning of those checkboxes.

`notify_user` validates the recipient and can add a deep link to a record.
Livespace provides no notification read-back, so the tool reports a successful
request as dispatched, never as delivered.

## Requirements

- A Livespace plan with API access, currently Automation or higher.
- One Livespace API key and secret from `Account settings -> API -> Users`.
  Use a dedicated Livespace API user with only the permissions this MCP needs.
  Every API operation inherits that user's permissions.
- Bun 1.3.14 or newer ([bun.sh](https://bun.sh)). The current server uses
  `Bun.serve` and has no Node.js or Cloudflare Workers adapter.

The v1 deployment model is single-user: one Livespace credential pair and, if
enabled, one MCP bearer token protects the server. There is no OAuth or
multi-user credential routing.

## Install and run from npm

The package is distributed through npm's public registry, but Bun is its
runtime. You do not need Node.js or the npm CLI to run it.

For a first evaluation, create a private working directory outside a Git
repository. Add a `.env` file there with your own Livespace credentials:

```dotenv
LIVESPACE_SUBDOMAIN=
LIVESPACE_API_KEY=
LIVESPACE_API_SECRET=
```

Fill the three empty values, protect the file, then start the published
package:

```bash
chmod 600 .env
bunx livespace-crm-mcp
```

The default endpoint is `http://127.0.0.1:3020/mcp`. Keep the process running
while your MCP client is connected. Start in read-only mode, call `health`,
then use `crm_metadata` before any operation that needs a user, process, stage,
group or dictionary ID.

`bunx` downloads the package from npm and caches it locally. To pin this
release, run `bunx livespace-crm-mcp@0.1.2`.

## Connect an MCP client

Configure a client that supports Streamable HTTP with this server URL:

```json
{
  "url": "http://127.0.0.1:3020/mcp"
}
```

The exact configuration field differs between clients. Set `MCP_AUTH_TOKEN`
and configure the client to send `Authorization: Bearer <your-token>`, even on
loopback. Authentication is mandatory when write tools are enabled.

This package exposes Streamable HTTP, not stdio. Some MCP clients can connect
to the local URL but cannot launch `bunx` for you, so start the command in a
separate terminal. Clients that accept only stdio are not supported yet. Each
HTTP request must contain one JSON-RPC message; top-level batch arrays are
rejected before dispatch.

## Read results

Record data goes in `structuredContent`, with a short text summary. Check that
your host passes both channels to its model. Empty `search_crm` and
`get_activity` pages include the same `hint` in both channels; follow a
returned cursor before concluding that no records match. An empty
`crm_metadata` user search also carries a hint in both channels. See the
[host compatibility checks](docs/host-compatibility.md) for tested versions,
confirmation limits and a synthetic fixture you can run without CRM access.

Use `crm_metadata` with `userQuery` to find a user by part of their name or
email. For example, `{"userQuery":"synthetic@example.test"}` returns only the
users section. The query must have 2-100 characters after trimming. Matching
ignores case but preserves accents; it does not search team names. If you
supply `sections`, it must include `users`; other requested sections remain
unfiltered. Omitting the query preserves the usual section selection.

The tool returns all matching users up to 500, in dictionary order. Resolve
multiple matches before choosing an owner or write recipient. `totalItems`
counts matches in the cached dictionary before that cap. Check `asOf`,
`ageMs` and `stale`, especially when a user is missing from the results.

Phrase-search links are generated locally from the API ID, without a separate
check of each destination. An unusable ID produces an empty `url`. Record
reads and filtered searches retain the URL supplied by Livespace, including
at `detail: "minimal"` for persons, companies and deals; that URL can also be
empty. Tasks have no record URL.

Fields excluded by `detail` are omitted. An empty or null returned value means
the response supplies no value; it does not establish an empty CRM field or
an access restriction. For deal value and probability, distinguish numeric
zero from null. A zero budget alone does not show whether someone set it
intentionally. Some counters and flags normalize missing data to zero or
false, so those defaults do not prove an explicitly stored value.

Deal `value` comes from whichever field the account fills. Accounts that use
budget lines keep the line sum in `value`. Other accounts report `value: 0`
on every deal and keep the value shown in the UI in `value_final`. The server
returns a non-zero `value_final` when there is one and `value` otherwise, so
`search_crm`, `get_records` and `analyze` agree with the UI on both kinds of
account.

At `detail: "full"`, deals also carry `checkedSteps` (the process steps marked
done, with stage and step ids and names) and the won, lost and outdated reason
names and notes. A reopened deal can keep an earlier lost reason, so check
`status` first. `search_crm` filters accept `createdFrom` and `createdTo` for
persons, companies and deals, and `modifiedFrom` for deals, all as inclusive
`YYYY-MM-DD` dates. Livespace ignores a date it cannot read and returns every
record, so the server rejects invalid dates before calling it. The deal
`status` filter takes `open` (the default), `won`, `lost`, `outdated` or `all`.

All tools reject unsupported input parameters. Correct the arguments when
the client reports an input validation error.

## Configuration

| Variable | Purpose |
|---|---|
| `LIVESPACE_SUBDOMAIN` | Account subdomain without protocol or `.livespace.io`. |
| `LIVESPACE_API_KEY` / `LIVESPACE_API_SECRET` | Credentials for one Livespace user. |
| `MCP_PORT` | Server port. Default: `3020`. |
| `MCP_BIND_HOST` | Bind address. Default: `127.0.0.1`. |
| `MCP_AUTH_TOKEN` | Random bearer token of at least 32 bytes. Required for writes and on a non-loopback bind; recommended for every server. |
| `LIVESPACE_MCP_ENABLE_WRITES` | Set to `true` to expose write tools. Default: `false`. |
| `LIVESPACE_MCP_READ_ONLY` | Emergency kill-switch. `true` removes and blocks write tools even when enabled above. |
| `MCP_REQUEST_STATE_KEY` | Independent random secret of at least 32 bytes used to sign write confirmations. Required when writes are enabled. |
| `MCP_ALLOW_UNBOUND_WRITE_CONFIRMATION` | Unsafe compatibility mode for clients without form elicitation. Default: `false`. |
| `MCP_ALLOWED_HOSTS` | Host-header allowlist for DNS-rebinding protection. Required on a non-loopback bind. |
| `MCP_ALLOWED_ORIGIN_HOSTNAMES` | Optional additional browser-origin hostnames. On a non-loopback bind it defaults to `MCP_ALLOWED_HOSTS`. |
|