Livespace CRM MCP Server

Livespace CRM MCP Server

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.3 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.

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

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). 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:

LIVESPACE_SUBDOMAIN=LIVESPACE_API_KEY=LIVESPACE_API_SECRET=

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

chmod 600 .envbunx 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 [email protected].

Connect an MCP client

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

{  "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 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":"[email protected]"} 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

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.

Write safety

The normal flow is elicitation-first:

1. dryRun: true builds a plan without writing or requesting approval.
2. On a client with form elicitation, a call without dryRun: true asks a human to approve the plan before execution. A confirm: true argument cannot bypass this prompt.
3. The confirmation exchange uses a signed 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.
4. If the relevant records changed before approval, the tool returns 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.
• A successful write can still report 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.

Security and privacy

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.

Incident response

If a Livespace key, bearer token or confirmation key may be compromised:

1. Stop the MCP server.
2. Immediately revoke the Livespace API key and issue a replacement for the dedicated API user.
3. Generate new, independent MCP_AUTH_TOKEN and MCP_REQUEST_STATE_KEY values.
4. Restart the server and update the MCP client's Bearer header.
5. Review Livespace's record and activity history for unexpected writes. Do not retry any operation that previously returned unknown_outcome.

v1 limits

• No delete or merge operations.
• No tag or custom-field writes in v1. Livespace documents tag changes through 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.
• Tasks created here cannot be linked to records. Livespace's 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.
• Logged notes and calls cannot be edited or removed.
• Deal updates cover name and status (open, won or lost); stage changes use 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.
• Reads and analyses use bounded windows. Inspect truncation fields before treating a result as complete.
• Missing values and mixed currencies can make monetary sums null; the result names the reason.
• API ids differ from the ids shown in the Livespace UI. Use IDs returned by crm_metadata, search_crm or another tool and never guess them.

Development

To work from source instead of the published package:

git clone https://github.com/proAutomator/livespace-crm-mcp.gitcd livespace-crm-mcpbun installcp .env.example .envbun run dev

The repository commands are:

bun test                 # complete offline suitebun run test:security    # focused security contract from docs/security.mdbun run typecheckbun run smoke            # live test-account check via .env or macOS Keychainbun run dev

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.

Disclaimer

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.

Attribution

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.

Author

Built by Kuba Masztalski

• LinkedIn: linkedin.com/in/kuba-masztalski
• X: @proAutomator

Bugs and feature requests: GitHub Issues. Security reports: see SECURITY.md.

License

MIT