The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Livespace CRM MCP Server listing page.
Unofficial MCP server for Livespace CRM. 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.1 is available on npm, in the official MCP Registry, and as a GitHub Release.
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.
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:
| 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. |
search_crm | Read | Finds persons, companies or deals. 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.
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.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.
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:
Fill the three empty values, protect the file, then start the published package:
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
security release, run bunx livespace-crm-mcp@0.1.1.
Configure a client that supports Streamable HTTP with this server URL:
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.
| 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. |
MCP_RATE_LIMIT_PER_MINUTE / MCP_RATE_LIMIT_BURST | Per-principal request rate. Defaults: 120 per minute and burst 30. |
MCP_MAX_CONCURRENT_REQUESTS / MCP_MAX_QUEUED_REQUESTS | Admission limits. Defaults: 8 in flight and 16 queued. |
MCP_REQUEST_INGRESS_TIMEOUT_MS | Absolute limit for admission queueing plus body upload, not tool execution. Default: 10000; maximum: 60000. |
MCP_REQUEST_EXECUTION_TIMEOUT_MS | Absolute limit for tool execution after upload. Default: 90000; maximum: 300000. |
The server refuses a non-loopback bind unless MCP_AUTH_TOKEN and
MCP_ALLOWED_HOSTS are set. It also refuses to enable writes without both
MCP_AUTH_TOKEN and MCP_REQUEST_STATE_KEY. Once MCP_AUTH_TOKEN is
configured, every /mcp request needs that Bearer token, including on
loopback. Host and Origin checks run before the MCP handler.
Generate independent values for MCP_AUTH_TOKEN and MCP_REQUEST_STATE_KEY
by running openssl rand -hex 32 twice. Do not reuse a Livespace credential.
The Bun process does not terminate TLS. Put a TLS-capable reverse proxy in
front of every network-exposed deployment. The server reads credentials from
environment variables, commonly through Bun's .env loading; protecting
.env at rest is the operator's responsibility. Never commit it. The smoke
script can also read the sandbox credentials from the macOS Keychain.
The normal flow is elicitation-first:
dryRun: true builds a plan and writes nothing.confirm: true argument cannot bypass this prompt.requestState that is valid for
five minutes and consumed after an accepted or declined response. It is
bound to the authenticated principal when present, the tool, arguments and
preview.recordsChanged: true, writes nothing and presents a fresh plan.Write execution is disabled by default on clients without form elicitation.
Those clients can preview, but confirm: true is refused. An operator can set
MCP_ALLOW_UNBOUND_WRITE_CONFIRMATION=true for compatibility. In that mode,
confirm: true executes without signed proof that a human saw the preview.
Results distinguish these cases:
verification: verified means the server re-read comparable fields after
the write.verification: unavailable when a
follow-up read failed, no sent field had an independent comparator or the
upstream API exposes no read-back. Inspect that item's error and re-read the
record where possible; do not retry the write.unknown_outcome means the request may or may not have landed. Never retry
it blindly.not_attempted means that item was not sent, usually because a time budget
expired or an earlier item hit the upstream rate limit. Those unsent items
can be submitted later; follow the error hint for the rate-limited item.Notification success is reported as dispatched, never as delivered. If delivery matters, confirm it by another channel instead of sending a duplicate notification.
CRM names, notes, imported e-mails, task text and wall entries are untrusted data. The server never evaluates them as instructions, but the MCP host and model can still be influenced by their contents. Keep writes disabled unless the client provides a human confirmation flow. Fetch only the records and detail level needed for the task.
Tool responses can be retained by the MCP host, model provider or local client logs. Choose a host whose storage, training and retention policy fits the CRM data you process. This server stores no CRM records on disk and sends no telemetry, but it cannot control what the host does after receiving a result.
Use a dedicated Livespace API user rather than an administrator's key. Give it the smallest useful record and write permissions. Evaluate the MCP against a separate test account before connecting it to business data.
For a reverse proxy, terminate TLS, disable caching and do not log MCP request
or response bodies. The server sets Cache-Control: no-store and
Vary: Authorization, but proxy policy must preserve those protections.
If a Livespace key, bearer token or confirmation key may be compromised:
MCP_AUTH_TOKEN and MCP_REQUEST_STATE_KEY
values.unknown_outcome.tag_add and tag_remove, and custom fields through dataset. Tag writes
still need a sandbox probe using those exact keys. Custom-field writes
cannot be verified until the sandbox has fields covering the supported
types, including answer ids for select fields.Todo/addTodo documentation
describes links through todo.objects, but our sandbox probe returned
success and echoed the submitted link while a fresh read returned
objects: []. The exact raw probe payload was not retained, so the result
is inconclusive. The server omits objects from task writes until a
controlled probe confirms that the link persists. Existing links returned
by Livespace are still exposed as linkedRecords.move_deals_to_stage. create_records can set budget lines when it creates
a deal, but update_records does not edit an existing budget because the
append-versus-replace behavior has not been verified.stage_conversion is a point-in-time estimate because Livespace exposes no
stage history.null; the
result names the reason.crm_metadata, search_crm or another tool and never guess them.To work from source instead of the published package:
The repository commands are:
bun run smoke and health with checkLivespace: true make real API calls.
Use only a test Livespace account, never a production CRM.
The binding threat model and regression map are in docs/security.md. Report vulnerabilities privately as described in SECURITY.md.
Community project. Not affiliated with, endorsed by or supported by Livespace S.A. "Livespace" is a trademark of its owner and is used here only to describe compatibility. Operations through the Livespace API run under your API key and, under Livespace's terms of service, at your responsibility.
This server follows patterns from Adam Gospodarczyk's (overment) MCP servers, especially iceener/streamable-mcp-server-template (MIT): a small intent-shaped tool surface, operating instructions, batch-first writes with per-item results and errors with recovery hints. Thanks, Adam.
Built by Kuba Masztalski
Bugs and feature requests: GitHub Issues. Security reports: see SECURITY.md.