Skip to main content
Glama
The-Keep-Studios

EspoCRM Assistant

by The-Keep-Studios
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

EspoCRM Assistant

Constrained EspoCRM access for issue #28. The assistant-visible MCP server can read records and prepare signed change sets; it cannot apply or delete anything. See the evaluation for the build-vs-wrap decision and security boundary.

This service requires an existing EspoCRM deployment. It does not install, enable, migrate, or administer EspoCRM. The Keep Platform or another GitOps repository should consume a published image from this repository and provide Kubernetes deployment configuration, secrets, probes, ingress, and operator runbooks.

Local Development

python -m venv .venv
. .venv/bin/activate
pip install -e .
export ESPOCRM_URL=https://crm.example.com
export ESPOCRM_READ_API_KEY=...
thekeep-espocrm-mcp

Run the dependency-free tests with:

PYTHONPATH=src python -m unittest discover -s tests -v

Related MCP server: safe-sql-mcp

Runtime Modes

The stdio MCP entrypoint is for local evaluation:

thekeep-espocrm-mcp

Run streamable HTTP MCP for an internal gateway:

export ESPOCRM_MCP_HOST=0.0.0.0
export ESPOCRM_MCP_PORT=8080
export ESPOCRM_MCP_PATH=/mcp
thekeep-espocrm-mcp-http

Do not expose the streamable HTTP endpoint directly to the internet. Production should keep it internal and place OAuth/OIDC and per-user authorization in front of it through the platform MCP gateway tracked by #54.

The container default command is the service HTTP entrypoint:

thekeep-espocrm-http

It exposes:

  • GET /healthz

  • authenticated POST /crm/* read and prepare endpoints using ESPOCRM_ASSISTANT_TOKEN

  • authenticated POST /approval/apply-change using ESPOCRM_ASSISTANT_APPLY_TOKEN

Apply a reviewed change set outside the assistant, either locally:

thekeep-espocrm-apply change.json \
  --approve-sha256 <sha256> \
  --approved-by <human-identity>

or through the deployed approval endpoint:

curl -fsS http://espocrm-assistant.espocrm.svc.cluster.local:8090/approval/apply-change \
  -H "Authorization: Bearer ${ESPOCRM_ASSISTANT_APPLY_TOKEN}" \
  -H "Content-Type: application/json" \
  --data @approved-change.json

approved-change.json must contain change, approved_sha256, and approved_by. The approval endpoint uses separate write credentials and is not registered as an MCP tool.

Use separate read-only and write-capable Espo API users. The executor reads ESPOCRM_WRITE_API_KEY; optional HMAC secrets use the same READ_/WRITE_ prefix. The deployed approval endpoint additionally requires ESPOCRM_ASSISTANT_APPLY_TOKEN and writes audit records to ESPOCRM_ASSISTANT_AUDIT_LOG. Writes require source attribution; Opportunity writes also require reciprocal signal evidence or an explicit human override. The executor rejects stale updates, adds an Espo Note, and appends a mode-0600 audit record.

Configuration

Use a least-privilege EspoCRM API user for reads and a separate write-capable API user for the approval executor. Do not reuse admin credentials.

Variable

Required

Purpose

ESPOCRM_URL

yes

Existing EspoCRM base URL. HTTPS is required unless ESPOCRM_ALLOW_HTTP=1.

ESPOCRM_READ_API_KEY

yes

Read-only EspoCRM API key used by assistant-visible tools.

ESPOCRM_READ_AUTH_METHOD

no

apikey by default; set hmac when using HMAC auth.

ESPOCRM_READ_SECRET_KEY

for read HMAC

HMAC secret for the read API user.

ESPOCRM_WRITE_API_KEY

for apply

Write-capable EspoCRM API key used only by approval/apply paths.

ESPOCRM_WRITE_AUTH_METHOD

no

apikey by default; set hmac when using HMAC auth.

ESPOCRM_WRITE_SECRET_KEY

for write HMAC

HMAC secret for the write API user.

ESPOCRM_ASSISTANT_TOKEN

for HTTP /crm/*

Bearer token for the custom JSON HTTP API.

ESPOCRM_ASSISTANT_APPLY_TOKEN

for HTTP apply

Separate bearer token for /approval/apply-change.

ESPOCRM_ASSISTANT_AUDIT_LOG

no

JSONL audit path; defaults under ~/.local/state/thekeep/.

ESPOCRM_ASSISTANT_HOST

no

HTTP service bind host; default 0.0.0.0.

ESPOCRM_ASSISTANT_PORT

no

HTTP service port; default 8080.

ESPOCRM_MCP_HOST

no

Streamable HTTP MCP bind host; default 127.0.0.1.

ESPOCRM_MCP_PORT

no

Streamable HTTP MCP port; default 8080.

ESPOCRM_MCP_PATH

no

Streamable HTTP MCP path; default /mcp.

ESPOCRM_MCP_STATELESS_HTTP

no

1 by default.

ESPOCRM_ALLOW_HTTP

no

Set to 1 only for disposable local testing against HTTP EspoCRM.

Image Publishing

The CI workflow tests the package and builds the container image on every pull request. Pushes to main and v* tags publish to GHCR by default:

ghcr.io/the-keep-studios/espocrm-assistant:sha-<git-sha>
ghcr.io/the-keep-studios/espocrm-assistant:vX.Y.Z

The workflow also publishes latest on main for convenience, but downstream GitOps deployments should pin a sha-* tag, release tag, or digest.

The OCI registry is replaceable. Set these repository variables/secrets before running the workflow if publishing somewhere other than GHCR:

  • variable OCI_REGISTRY: registry hostname, for example registry.example.com

  • variable OCI_IMAGE: full image name, for example registry.example.com/thekeep/espocrm-assistant

  • variable OCI_USERNAME: registry username when it differs from the GitHub actor

  • secret OCI_PASSWORD: registry password or token

For non-GitHub installs, build or mirror the image with standard OCI tooling and update the consuming platform manifest to that immutable tag or digest.

Available Tools

7 tools
crm_duplicate_candidatesC

Find possible duplicates from identifying fields.

ParametersJSON Schema
NameRequiredDescriptionDefault
fieldsYes

TDQS

C2.1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states 'Find possible duplicates' but does not disclose any behavioral traits such as whether results are returned, if it is read-only, or what happens with the fields parameter. The description is insufficient for an agent to understand side effects or constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short, but it is under-specified rather than concise. A single sentence that lacks necessary details does not earn high marks for conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a complex object parameter, no output schema, and no annotations, the description is severely inadequate. It does not explain the return format, how the fields object affects results, or any constraints, leaving the agent with insufficient context to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema coverage is 0%, and the description only mentions 'identifying fields' without explaining the structure or expected keys/values of the 'fields' parameter. The agent cannot infer how to populate the object parameter correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds possible duplicates using identifying fields, with a specific verb and resource. It implicitly contrasts with sibling tools like crm_get (single record) and crm_search (general search), but does not explicitly differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like crm_search or crm_get. The description lacks context about prerequisites, typical use cases, or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crm_export_csvC

Export validated change sets as CSV for manual import.

ParametersJSON Schema
NameRequiredDescriptionDefault
changesYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description must disclose behavioral traits. It does not mention whether the tool is read-only or has side effects. Only 'export' and 'CSV' hint at non-destructiveness, but permissions and behavior are unclear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that starts with the action. It is not verbose, but it could include parameter details without becoming too long.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has one required parameter and an output schema, the description is too minimal. It does not explain input structure or output format, leaving the agent with significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not explain the 'changes' parameter. The agent cannot infer what constitutes a validated change set or how to structure the input.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool exports validated change sets as CSV for manual import, with a specific verb and resource. It distinguishes from siblings like crm_get or crm_prepare_change, which do not export CSV.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as after preparing changes or to facilitate manual import. The description lacks context for proper selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crm_getC

Read one allowlisted CRM record.

ParametersJSON Schema
NameRequiredDescriptionDefault
entityYes
record_idYes
fieldsNo

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates a read operation ('Read'), implying no side effects, but no annotations exist. It does not disclose authentication needs, rate limits, or what 'allowlisted' means in practice. Minimal behavioral context is provided.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but under-specified. It lacks structure and does not earn its place by providing sufficient detail for an agent to correctly invoke the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (3 parameters, no output schema, 0% schema coverage), the description is severely incomplete. It does not explain the allowed entities, record ID format, fields parameter, or return behavior. An agent would lack critical information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage and no explanation of the three parameters (entity, record_id, fields), the description fails to add meaning beyond the schema. It does not clarify allowed entities, record ID format, or fields usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Read') and resource ('CRM record'), and the qualifier 'allowlisted' suggests a restriction. It distinguishes from sibling tools like crm_search which retrieves multiple records. However, 'allowlisted' is ambiguous without further explanation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like crm_search for multiple records or crm_metadata for schema information. The description does not mention prerequisites or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crm_metadataA

Read allowlisted field metadata for one entity.

ParametersJSON Schema
NameRequiredDescriptionDefault
entityYes

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description says 'Read' suggesting read-only but does not confirm idempotency, auth requirements, or error handling. Minimal behavioral disclosure given a simple read operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded, no unnecessary words. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Low complexity tool but no output schema and description does not explain what 'field metadata' includes or return format. Lacks completeness for a metadata retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single parameter 'entity' lacks schema description (0% coverage) and the description only says 'one entity' without specifying whether it is a name, ID, or valid values. Does not compensate for missing schema info.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'Read', resource 'field metadata', and specificity 'allowlisted' and 'for one entity'. Differentiates from sibling tools which handle records, duplicates, or exports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies usage for retrieving metadata about a single entity, but does not explicitly state when to use this over siblings like crm_get or crm_search. Context from sibling names partially fills the gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crm_prepare_changeC

Prepare and hash a non-mutating create or update change set.

ParametersJSON Schema
NameRequiredDescriptionDefault
requestYes

TDQS

C2.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description must fully disclose behavior. It states 'non-mutating,' indicating no side effects, and mentions hashing, suggesting a change set is prepared and hashed without persistence. However, it lacks details on error handling, permissions, or what constitutes a valid request. Adequate but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short (one sentence). While concise, it sacrifices informative value. For a tool with one parameter and no annotations, a slightly longer description that adds parameter guidance would be more beneficial without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (nested object parameter, no output schema, multiple siblings), the description is insufficient. It does not explain the hash's purpose or how the output should be used. Sibling tools exist but are not referenced for comparison.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The single parameter 'request' is an object with additionalProperties: true, but the description provides no explanation of its expected structure, fields, or constraints. For a parameter-heavy tool, this is a critical gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('prepare and hash') and object ('non-mutating create or update change set'). It distinguishes from sibling tools by specifying 'non-mutating', implying no data modification. However, the phrase 'non-mutating create or update' is slightly contradictory and could be clearer.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus its siblings (e.g., crm_get, crm_search). No mention of prerequisites, when not to use, or alternatives. The description only states what the tool does without context for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crm_prepare_lead_conversionC

Prepare linked Lead-to-Opportunity change sets for human approval.

ParametersJSON Schema
NameRequiredDescriptionDefault
requestYes

TDQS

C2.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It indicates a preparatory step for human approval, but does not disclose side effects, permissions needed, or whether state is modified. The behavioral disclosure is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, terse sentence. While concise, it is underspecified for the complexity of the tool (nested object parameter, no schema descriptions). Key information is missing, so it does not earn its place as an adequate description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations, no output schema, and a poorly defined parameter, the description fails to provide necessary context. It does not mention return values, prerequisites, or how the change set is used afterward. The tool is inadequately documented.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no meaning beyond the input schema. The single 'request' parameter is an opaque object with additionalProperties true, and schema description coverage is 0%. The agent has no guidance on what to include in the request, making the tool essentially unusable without external knowledge.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'prepare linked Lead-to-Opportunity change sets for human approval,' clearly indicating the action (prepare), resource (Lead-to-Opportunity change sets), and context (for human approval). However, it does not explicitly differentiate from sibling tool crm_prepare_change, which may have overlapping functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when converting a lead to an opportunity requiring approval, but no explicit guidance on when to use this vs. alternatives like crm_prepare_change, nor are there exclusions or prerequisites stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv0.1.0
    • First observedcrm_duplicate_candidates
    • First observedcrm_export_csv
    • First observedcrm_get
    • First observedcrm_metadata
    • First observedcrm_prepare_change
    • First observedcrm_prepare_lead_conversion
    • First observedcrm_search
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3/5.0
Disambiguation5/5

Each tool targets a distinct CRM operation: duplicate detection, CSV export, single record retrieval, metadata, change preparation, lead conversion preparation, and search. No overlap in functionality; an agent can easily distinguish them.

Naming Consistency4/5

All tools use the 'crm_' prefix with a verb-based name, e.g., 'crm_search', 'crm_get'. However, 'crm_get' lacks a noun (like 'record'), and 'crm_metadata' uses a noun as a verb, which is slightly inconsistent but still clear.

Tool Count5/5

Seven tools is well-scoped for a CRM assistant focused on read, search, duplicate detection, and preparation of change sets for human approval. No unnecessary tools, and the count supports a focused workflow.

Completeness4/5

The toolset covers core read, search, metadata, duplicate checking, change preparation, lead conversion preparation, and export. Missing direct mutation (create/update/delete) is intentional for a non-mutating, human-approval workflow. A minor gap is the lack of a list-all-entities tool, but search can compensate.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Secureframe MCP Server by secureframe

    Secureframe MCP Serverofficial

    secureframe
    A
    license
    Not graded
    quality
    F
    maintenance
    Provides AI assistants with read-only access to Secureframe's compliance data, enabling querying of security controls, tests, users, vendors, and more across frameworks like SOC 2 and ISO 27001.
    8
    MIT

  • safe-sql-mcp

    ahmedabdirahman1-max
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables read-only SQL database access for AI assistants, allowing schema exploration and safe query execution without risk of data modification.
    -

  • InvoiceNinja MCP Server

    a-wiseguy
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables read-only access to InvoiceNinja data, including invoices, expenses, clients, and tax reports, for AI assistants like Claude.
    1
    -

  • DB MCP Gateway

    mdadul
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides read-only access to databases for MCP-compatible AI tools, allowing schema exploration and SELECT queries without exposing credentials or risking data changes.
    83
    3
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/The-Keep-Studios/espocrm-assistant'

If you have feedback or need assistance with the MCP directory API, please join our Discord server