@vennyx/solicrm-mcp

MCP server for SoliCRM — exposes contacts, companies, deals, pipelines, activities, tasks, notes, saved views and cross-resource search as tools an AI agent can call.

Every tool is a thin wrapper around the typed @vennyx/solicrm SDK, and its input schema is the zod schema the SoliCRM API validates against — the tool surface cannot drift from the API.

Two ways to connect

| | Hosted, OAuth (recommended) | Local, API key (this package) | | --- | --- | --- | | Address | https://api.solicrm.com/mcp | npx @vennyx/solicrm-mcp (stdio) | | Identity | Browser sign-in (OAuth 2.1 + PKCE + DCR) | SOLICRM_API_KEY | | Secret in your config | none — not even a header | yes | | Tenant | you pick it on the consent screen | fixed by the key | | Needs a browser | yes, once | no | | Best for | desktop / human use | CI, cron, headless servers |

Both are supported; neither replaces the other.

Hosted server with OAuth — no secrets in your config

SoliCRM hosts this exact server at POST https://api.solicrm.com/mcp. Point a client at that URL and it discovers the authorization server on its own, registers itself dynamically (RFC 7591), and sends you to the browser to sign in.

claude mcp add --transport http solicrm https://api.solicrm.com/mcp
claude mcp login solicrm

Or, committed to a repo as .mcp.json — safe to share, it contains no secret:

{
  "mcpServers": {
    "solicrm": {
      "type": "http",
      "url": "https://api.solicrm.com/mcp"
    }
  }
}

During sign-in you choose which tenant the connection is for. The granted scope is your requested scope intersected with your current role ceiling in that tenant, and it is recomputed on every request — being demoted or removed takes effect immediately.

claude mcp logout solicrm revokes the refresh token. Note that the access token is a stateless JWS and stays valid for at most one hour after that; to cut access off instantly, remove the membership or suspend the tenant.

Full guide (Turkish), including operator setup: docs/ops/2026-07-28-mcp-baglanti-ve-oauth.md in the SoliCRM repository.

Install (API key / stdio)

No install needed — run it with npx:

SOLICRM_API_KEY=scrm_… SOLICRM_TENANT_ID=… npx @vennyx/solicrm-mcp

Requires Node.js ≥ 18 (or Bun). ESM only.

Claude Code / Claude Desktop

{
  "mcpServers": {
    "solicrm": {
      "command": "npx",
      "args": ["-y", "@vennyx/solicrm-mcp"],
      "env": {
        "SOLICRM_API_KEY": "scrm_…",
        "SOLICRM_TENANT_ID": "00000000-0000-0000-0000-000000000000"
      }
    }
  }
}

This form does carry a secret — keep it out of version control and feed it from the environment.

Environment variables

| Variable | Required | Meaning | | --- | --- | --- | | SOLICRM_API_KEY | yes | Tenant API key, starts with scrm_. Create it under Dashboard → API keys. | | SOLICRM_TENANT_ID | yes | UUID of the tenant the key belongs to. | | SOLICRM_BASE_URL | no | API base; defaults to https://api.solicrm.com. | | SOLICRM_SCOPE | no | read | write | admin. Filters tools/list only — see “Scopes” below. Defaults to admin. |

A missing or empty SOLICRM_API_KEY/SOLICRM_TENANT_ID is a hard startup error (in Turkish, matching the rest of the product) — the process never starts up silently half-configured.

Transports

solicrm-mcp                # stdio (default)
solicrm-mcp --http         # standalone Streamable HTTP on 127.0.0.1:3737, POST /mcp
solicrm-mcp --http 8080    # …on a custom port
solicrm-mcp --help
solicrm-mcp --version

The HTTP mode is stateless (a fresh server per request), binds to loopback by default and answers anything other than POST /mcp with an error — it is a self-host convenience, not a public endpoint. SoliCRM also hosts the same server at POST /mcp on its own API, so most users never need this flag.

Tools

22 tools: list_contacts, get_contact, create_contact, update_contact, list_companies, get_company, create_company, update_company, list_deals, get_deal, create_deal, update_deal, move_deal_stage, list_pipelines, list_activities, create_activity, list_tasks, create_task, complete_task, create_note, search, list_saved_views.

Two resources (solicrm://contacts/{id}, solicrm://deals/{id}) and one prompt (summarize_pipeline).

Tenant isolation and scopes

• No tool takes a tenantId argument and no resource URI carries a tenant segment. The tenant always comes from the API key, so “reach into another tenant” is not a check that can fail — it is structurally impossible.
• SOLICRM_SCOPE only decides which tools are advertised. The real authorization is recomputed by the SoliCRM API on every single request from the key's scope intersected with the current role ceiling of the key's owner. Demoting the owner takes effect immediately, even for an already-running server process.

Errors

Tool failures come back as isError: true with the server's message verbatim (Turkish). Unexpected internal failures are reduced to a single generic message — raw upstream text is never forwarded to the agent.

Related

• @vennyx/solicrm — the typed SDK these tools are built on.

License

MIT © Vennyx A.Ş.