Skip to main content
Glama
MartinCley

Excel MCP Cleyrop

by MartinCley

Génération Excel → Cleyrop MCP

Serveur MCP qui génère des fichiers Excel (.xlsx) mis en forme à partir d'une demande utilisateur et les dépose dans les données de travail d'un projet Cleyrop (via cleyrop-sdk).

POC inspiré de la note interne « Génération de documents », packagé selon la convention des tools MCP de La Fabrique (même structure que tool-sharepoint).

Principe : séparer contenu et mise en forme

Le LLM ne produit jamais de mise en forme : il produit du contenu structuré, et un moteur de rendu distinct applique le style depuis un thème.

LLM ──> Contenu structuré (WorkbookSpec) ──> Moteur de rendu (openpyxl) ──> Thème ──> .xlsx
                                                                                        │
                                                          cleyrop-sdk.upload_file()  ──▶  Données de travail (projet Cleyrop)

Avantages : on change de thème sans toucher au prompt, on teste contenu et rendu séparément, et le même contenu pourrait alimenter d'autres formats plus tard. Bibliothèque : openpyxl (recommandée dans la note).

Related MCP server: excel-mcp-server

Tools exposés

Tool

Rôle

generate_excel(spec, project=None, cleyrop_folder=None, user=None)

Génère le .xlsx. Sans project : renvoie le fichier en ressource téléchargeable (blob xlsx). Avec project : tente le dépôt dans les données de travail (nécessite des droits d'écriture).

cleyrop_list_projects()

Lister les projets Cleyrop (id / slug) pour le paramètre project

cleyrop_diagnose()

Diagnostiquer l'authentification Cleyrop (sans fuite de secret)

get_excel_schema()

JSON Schema complet de la WorkbookSpec attendue

Téléchargement vs dépôt. Les tokens personnels Cleyrop sont en lecture seule : ils ne permettent pas d'écrire dans un projet. Le mode par défaut (sans project) renvoie donc le fichier en téléchargement. Le dépôt (project) ne réussit qu'avec un compte de service disposant des droits d'écriture (client_credentials injectés par La Fabrique).

Déploiement 100 % interne (cas Cleyrop). Si le tool n'a pas d'URL publique (image buildée et déployée sur la plateforme, connexions chat→tool internes), un lien de téléchargement servi par le tool n'est pas joignable depuis le navigateur de l'utilisateur. La livraison se fait alors par dépôt dans un projet : définis EXCEL_MCP_DEFAULT_PROJECT (ou CLEYROP_PROJECT_SLUG) et le fichier est déposé dans les données de travail, où l'utilisateur le télécharge depuis l'UI Projets. Le dépôt exige un compte de service avec droits d'écriture (vérifie avec cleyrop_diagnose).

Ressource MCP lisible (sans URL). generate_excel joint aussi le fichier comme ressource MCP (ResourceLink vers excel://download/{token}, + blob embarqué). Un client qui sait lire les ressources peut récupérer le fichier via la connexion MCP elle-même (resources/read), sans aucune URL publique. Dépend du support côté client (panneau ressources / pièces jointes).

Lien de téléchargement HTTP (si URL publique). Le serveur expose aussi une route GET /download/{token}. À n'utiliser que si le tool est exposé publiquement : renseigne alors EXCEL_MCP_PUBLIC_URL.

Capacités de rendu

Multi-feuilles · titre · entêtes stylées · colonnes typées (text/number/integer/currency/percent/date/datetime) · formats de nombre auto ou personnalisés · largeurs auto · zébrage · volet figé · filtres · ligne de totaux (sum/avg/count/min/max via formules Excel) · mise en forme conditionnelle (color_scale/data_bar/greater_than/less_than) · graphiques natifs (bar/line/pie) · thèmes (cleyrop, default, minimal).

Architecture

Fichier

Rôle

src/excel_mcp/models.py

Schéma du contenu (Pydantic) : classeur → feuilles → colonnes typées → lignes

src/excel_mcp/themes.py

Thèmes de mise en forme (couleurs, polices)

src/excel_mcp/renderer.py

Moteur de rendu : spec → openpyxl.Workbook

src/excel_mcp/cleyrop_io.py

Wrapper cleyrop-sdk (dépôt dans les données de travail)

src/excel_mcp/storage.py

Nommage {timestamp}_{user}_{type}_{slug}.xlsx + stockage local (fallback)

src/excel_mcp/server.py

Serveur MCP (FastMCP) exposant les tools

main.py

Point d'entrée conteneur (transport HTTP streamable-http)


1. Configuration côté Cleyrop

Le client cleyrop-sdk est construit dans src/excel_mcp/cleyrop_io.py selon le pattern de production des tools/apps Cleyrop. Deux modes d'authentification, par ordre de priorité :

Priorité

Mode

Variables

Comportement

1

Compte de service

CLEYROP_CLIENT_ID + CLEYROP_CLIENT_SECRET

Flux client_credentials. Identité injectée par La Fabrique au déploiement (rien à mettre dans le code — cf. Assistant_Contrat). Prioritaire si présent.

2

Token pré-obtenu

CLEYROP_TOKEN

Token de service ou personnel, utilisé tel quel (Bearer), sans login. Utilisé seulement si aucun client_secret n'est présent.

⚠️ Le compte de service est prioritaire sur CLEYROP_TOKEN : un token résiduel ou invalide ne peut donc pas masquer les client_credentials injectés par la plateforme. Si tu veux forcer l'usage d'un token personnel, ne fournis pas de client_secret.

Les CLEYROP_CLIENT_ID / CLEYROP_CLIENT_SECRET ne sont jamais stockés dans le dépôt : ils sont injectés par La Fabrique au niveau de l'instance (le .env d'Assistant_Contrat ne les contient pas non plus). Le code se contente de les lire via os.getenv.

Résolution des URL (auto-détectée) : in-cluster par défaut (FQDN apisix-gateway.<namespace>.svc.cluster.local, CLEYROP_NAMESPACE), ou externe via CLEYROP_DOMAIN, ou override explicite via CLEYROP_API_URL + CLEYROP_KEYCLOAK_URL. Voir .env.example.

Dans un Tool/App de La Fabrique, ces variables sont normalement injectées automatiquement. Détails : doc cleyrop-sdk.

Le package cleyrop-sdk est privé (registre GitLab) : l'installation nécessite UV_INDEX_CLEYROP_SDK_GITLAB_USERNAME / ..._PASSWORD (injectées au build).

2. Installation (DevSpace)

cd /home/cleyrop/tool-excel
uv venv && source .venv/bin/activate

# cleyrop-sdk vient d'un registre privé GitLab :
export UV_INDEX_CLEYROP_SDK_GITLAB_USERNAME=...
export UV_INDEX_CLEYROP_SDK_GITLAB_PASSWORD=...
uv sync

Copie .env.example.env si besoin de surcharger des variables.

3. Build de l'image (Docker / La Fabrique)

Le Dockerfile suit la convention des tools MCP Cleyrop : base astral/uv, uv sync, serveur exposé en HTTP (streamable-http) sur le port MCP_PORT (défaut 8000, endpoint /mcp).

cleyrop-sdk est résolu par uv via l'index cleyrop-sdk-gitlab déclaré dans pyproject.toml ; uv s'authentifie avec les variables UV_INDEX_CLEYROP_SDK_GITLAB_USERNAME / _PASSWORD injectées par l'environnement de build Cleyrop — aucun secret à passer au build.

# build local (hors Cleyrop) : exporter d'abord les credentials du registre
export UV_INDEX_CLEYROP_SDK_GITLAB_USERNAME=...
export UV_INDEX_CLEYROP_SDK_GITLAB_PASSWORD=...
docker build -t excel-cleyrop-mcp .
docker run --rm -p 8000:8000 --env-file .env excel-cleyrop-mcp

Dans La Fabrique : Registre interne → Créer une image → Dépôt interne → dépôt tool-excel, branche v1, chemin du Dockerfile Dockerfile.

Variables d'environnement de l'instance (Cleyrop)

Variable

Portée

Valeur

MCP_PORT

globale

8000 (= « port exposé » de l'instance)

MCP_HOST

globale (option)

0.0.0.0

MCP_TRANSPORT

globale (option)

streamable-http

EXCEL_MCP_DEFAULT_PROJECT

globale (recommandé en interne)

Projet Cleyrop où déposer par défaut (id/slug) quand aucun project n'est passé. CLEYROP_PROJECT_SLUG accepté en alias.

EXCEL_MCP_PUBLIC_URL

globale (si URL publique)

URL publique du tool (sans /mcp), pour les liens de téléchargement. Inutile en déploiement 100 % interne.

(client credentials cleyrop-sdk)

globale

injectées par La Fabrique (sinon .env)

4. Usage local (client MCP de bureau, stdio)

Pour tester sans déploiement, le serveur tourne aussi en stdio via la commande excel-cleyrop-mcp :

{
  "mcpServers": {
    "excel-cleyrop": {
      "command": "/home/cleyrop/tool-excel/.venv/bin/excel-cleyrop-mcp",
      "env": { "EXCEL_MCP_EXPORT_DIR": "~/.excel-mcp/exports" }
    }
  }
}

Sans paramètre project, generate_excel sauvegarde le fichier localement (EXCEL_MCP_EXPORT_DIR) — pratique pour tester le rendu sans projet Cleyrop.

Exemple d'usage (depuis un client MCP)

  1. cleyrop_list_projects() → récupère l'id/slug du projet.

  2. « fais-moi un tableau Excel des ventes T1 par région avec totaux et un graphique, dépose-le dans le projet X » → le LLM construit la WorkbookSpec et appelle generate_excel(spec, project="X", cleyrop_folder="exports/2026").

Voir examples/example_spec.json pour une spec complète (devise, pourcentages, dates, totaux, mise en forme conditionnelle, graphique).

Tests

PYTHONPATH=src python -m pytest tests/ -q

Tests de non-régression du moteur de rendu (contenu, formats, formules, nommage).

Feuille de route

  • Pré-visualisation : convertir le .xlsx en aperçu (cf. note : XLSX→PDF via Gotenberg, déjà utilisé pour le flux DOCX).

  • Templates XLSX versionnés : lire un classeur modèle (entêtes/styles nommés) plutôt que tout générer from scratch — openpyxl le permet.

  • Génération incrémentale pour les gros classeurs (plan → données → validation → assemblage).

Available Tools

4 tools
cleyrop_diagnoseA

Diagnostique la connexion Cleyrop (auth + accès API), sans exposer de secret.

À utiliser quand un dépôt échoue. Renvoie le mode d'URL et d'auth réellement vus par le serveur (token présent ? longueur ? secret ?), l'URL d'API résolue, et le résultat d'un appel réel me() qui distingue : token absent (variable non injectée -> redéployer), token invalide (401), réseau injoignable, ou OK avec l'identité authentifiée.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

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

Discloses that it does not expose secrets ('sans exposer de secret') and describes the output in detail (URL mode, auth mode, token presence, me() result). No side effects mentioned, but typical diagnostic tool is read-only.

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?

The description is concise and well-structured, starting with purpose, then usage, then detailed output. Every sentence adds value with no redundancy.

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

Completeness5/5

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

Despite lacking annotations and output schema, the description is highly complete: it explains purpose, when to use, exact output (URL, auth, token status, me() result with four outcomes), and safety (no secrets). Suitable for an agent to understand and invoke correctly.

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

Parameters4/5

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

No parameters exist, so schema coverage is 100%. Description adds no parameter information since none are needed; baseline of 4 is appropriate.

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 diagnoses Cleyrop connection (auth + API access) without exposing secrets. It specifies what is returned and differentiates from siblings (list projects, generate excel, get excel schema) by being a diagnostic tool.

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?

The description explicitly states 'À utiliser quand un dépôt échoue' (use when a deposit fails), providing clear context. It does not give exclusions but sufficiently guides when to use.

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

cleyrop_list_projectsA

Liste les projets Cleyrop accessibles (id, nom, slug).

Utile pour récupérer l'id ou le slug à passer comme paramètre project de generate_excel.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior3/5

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

No annotations provided. Description implies read-only (list) but doesn't explicitly state safety or side effects. Adequate for a simple list 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?

Two sentences with no waste; front-loaded with action and purpose. Highly efficient.

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

Completeness5/5

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

Complete for a parameterless list tool: mentions fields returned, has output schema, ties to sibling tool. No gaps.

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

Parameters4/5

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

No parameters exist (baseline 4). Description adds meaning by listing returned fields and linking to another tool's 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 tool lists Cleyrop projects and returns fields (id, name, slug). It does not explicitly differentiate from siblings but ties usage to another tool.

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

Usage Guidelines5/5

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

Explicitly states that the tool is useful for retrieving project id/slug to use as a parameter in 'generate_excel', providing clear when-to-use context.

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

generate_excelA

Génère un classeur Excel (.xlsx) et le livre à l'utilisateur.

Le LLM appelant fournit le CONTENU (feuilles, colonnes typées, lignes, options comme totaux/graphiques). Le serveur construit le fichier, applique le thème, puis le livre :

  • si un projet est ciblé (project, ou défaut EXCEL_MCP_DEFAULT_PROJECT / CLEYROP_PROJECT_SLUG) : dépose le fichier dans les données de travail du projet Cleyrop, où l'utilisateur le télécharge via l'UI. Nécessite un compte de service avec droits d'écriture (un token personnel est en lecture seule).

  • sinon : renvoie un lien de téléchargement HTTP (utile seulement si le tool a une URL publique, EXCEL_MCP_PUBLIC_URL) + le blob embarqué.

ParametersJSON Schema
NameRequiredDescriptionDefault
specYes
projectNoId ou slug du projet Cleyrop où DÉPOSER le fichier (cf. cleyrop_list_projects). Nécessite un compte de service avec droits d'écriture. Si absent, le fichier est renvoyé en TÉLÉCHARGEMENT.
cleyrop_folderNoDossier de destination dans les données de travail (créé si absent). Vide = racine du projet.
userNoIdentifiant/email du demandeur, pour le nommage et l'audit.

TDQS

A4/5.0
Behavior4/5

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

The description covers key behaviors: file construction, theme application, and two delivery modes with conditions (project vs. download). It also mentions authentication requirements (service account). Without annotations, it provides good transparency but could mention potential side effects or limits.

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 well-structured with bullet points and sections, front-loading the purpose and then detailing delivery modes. It is appropriately sized for the tool's complexity, though slightly verbose.

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

Completeness3/5

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

Given the complex spec and no output schema, the description could elaborate more on the output format (e.g., structure of the download link and blob). It adequately covers delivery modes and auth, but gaps in output details reduce completeness.

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

Parameters3/5

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

Schema description coverage is high (75%), and the schema already thoroughly documents parameters and nested objects like Workbookspec. The description adds little beyond repeating some delivery details, so it adds limited value over the schema.

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 generates an Excel workbook (.xlsx) and delivers it to the user, specifying two distinct delivery methods (project deposit or download link). It distinguishes itself from siblings like 'get_excel_schema' and 'cleyrop_list_projects' by focusing on generation and delivery.

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?

The description provides clear context for when to use this tool (to generate Excel files) and outlines prerequisites like service account permissions for project deposit. However, it does not explicitly state when not to use it or offer direct alternatives beyond the sibling tools listed.

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

get_excel_schemaA

Retourne le JSON Schema complet de la spécification attendue par generate_excel.

Décrit feuilles, colonnes, types, formats de nombre, totaux, graphiques et mise en forme conditionnelle.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

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

No annotations provided, so description must carry the burden. It correctly describes the return as a JSON Schema with details. It does not mention side effects, but as a read-only schema getter, no additional disclosure is necessary.

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?

Two concise sentences: first states the primary action, second lists what the schema covers. No unnecessary words.

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

Completeness5/5

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

Given zero parameters and the existence of an output schema, the description is complete. It specifies what the schema describes, leaving detailed structure to the output schema.

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

Parameters4/5

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

No parameters exist, so schema coverage is 100% vacuously. The description adds no parameter info, but baseline is 4 for zero parameters.

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 it returns the complete JSON Schema for generate_excel's specification, specifying the resource (JSON Schema) and its purpose (expected by generate_excel). It distinguishes itself from the sibling tool generate_excel.

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?

Implies usage context: use before calling generate_excel to understand input format. No explicit when-not or alternatives mentioned, but clear enough for a simple schema retrieval tool.

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. 4 tool updatesv0.1.0
    • First observedcleyrop_diagnose
    • First observedcleyrop_list_projects
    • First observedgenerate_excel
    • First observedget_excel_schema

TDQS

A4.1/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: diagnose troubleshoots connections, list_projects retrieves project identifiers, generate_excel creates the file, and get_excel_schema provides data structure. No overlap.

Naming Consistency3/5

Naming is inconsistent: two tools use a 'cleyrop_' prefix while two use a direct verb_noun pattern (generate_excel, get_excel_schema). While readable, the lack of a uniform convention causes mild confusion.

Tool Count4/5

With 4 tools, the set is on the smaller side but well-scoped for the core task of generating Excel files. It covers necessary utility actions without being overly sparse.

Completeness4/5

The tools cover the main workflow: diagnose, list projects, generate, and schema retrieval. Minor gaps like lacking a tool to list generated files or manage projects are acceptable given the focused purpose of Excel generation.

Maintenance

ActivityInactive
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

  • F
    license
    A
    quality
    D
    maintenance
    Enables LLMs to automatically generate Excel files with custom structures, advanced formatting, multiple sheets, formulas, and charts from JSON schemas, with support for both local and remote deployment.
    1
    -
  • A
    license
    A
    quality
    D
    maintenance
    Enables reading and writing Excel workbooks (.xlsx) through MCP. Supports listing sheets, tables, pivot tables, reading cell data, exporting to CSV/text/Markdown, and creating/modifying Excel files.
    14
    GPL 3.0
  • A
    license
    Not graded
    quality
    B
    maintenance
    Provides full read and write access to Excel workbooks (sheets, cell ranges, tables, formulas, formatting, and cross-workbook references) via MCP, running locally or as an HTTP/SSE service.
    70
    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/MartinCley/Excel-MCP'

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