@mnicole-dev/pappers-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maxime Nicole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# Pappers MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@mnicole-dev/pappers-mcp-server.svg)](https://www.npmjs.com/package/@mnicole-dev/pappers-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+MCP (Model Context Protocol) server for the [Pappers API](https://www.pappers.fr/api) — official information about French companies (SIREN / SIRET / financial data / officers / public records).
+
+Lets an MCP client (Claude Desktop, Claude Code, Cursor, etc.) search and fetch up-to-date legal and financial data on French entities.
+
+## Installation
+
+No install needed — run on demand via `npx`. The MCP client launches it as a child process and pipes JSON-RPC over stdio.
+
+## Configuration
+
+One environment variable required :
+
+| Variable | Description |
+|----------|-------------|
+| `PAPPERS_API_TOKEN` | API key from your Pappers account (see [pappers.fr/api](https://www.pappers.fr/api)) |
+
+### Claude Code (or Claude Desktop)
+
+Edit your MCP servers configuration (`~/.claude.json` for Claude Code, `~/Library/Application Support/Claude/claude_desktop_config.json` for Claude Desktop) and add :
+
+```json
+{
+  "mcpServers": {
+    "pappers": {
+      "command": "npx",
+      "args": ["-y", "@mnicole-dev/pappers-mcp-server"],
+      "env": {
+        "PAPPERS_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+Restart your MCP client.
+
+### Cursor
+
+Add to `.cursor/mcp.json` (project-level) or global Cursor settings :
+
+```json
+{
+  "mcpServers": {
+    "pappers": {
+      "command": "npx",
+      "args": ["-y", "@mnicole-dev/pappers-mcp-server"],
+      "env": {
+        "PAPPERS_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+## Available tools
+
+| Tool | Description |
+|------|-------------|
+| `search-company` | Search for French companies by name, SIREN or SIRET |
+| `get-company` | Fetch detailed info on a company (legal form, officers, address, activity codes) |
+| `get-finances` | Fetch up to 3 years of financial statements (revenue, net profit, equity, headcount) |
+| `get-dirigeants` | List active officers and directors of a company |
+| `search-dirigeant` | Search for officers by name |
+
+All tools accept friendly arguments validated via [Zod](https://github.com/colinhacks/zod).
+
+## Local development
+
+```bash
+git clone https://github.com/mnicole90/pappers-mcp-server.git
+cd pappers-mcp-server
+npm install
+npm run build
+```
+
+To run locally with an MCP client during development :
+
+```bash
+node dist/index.js
+```
+
+The server communicates over stdio.
+
+## API rate limits
+
+Pappers free tier : 100 requests / day.
+
+Paid plans give higher quotas — see [pappers.fr/api/tarifs](https://www.pappers.fr/api/tarifs).
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Author
+
+[Maxime Nicole](https://github.com/mnicole90) — [KodeSaaS](https://kodesaas.com)

package/dist/index.js

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var BASE_URL = "https://api.pappers.fr/v2";
+function getApiToken() {
+  const token = process.env["PAPPERS_API_TOKEN"];
+  if (!token) throw new Error("PAPPERS_API_TOKEN environment variable is required");
+  return token;
+}
+async function pappers(endpoint, params) {
+  const url = new URL(`${BASE_URL}${endpoint}`);
+  url.searchParams.set("api_token", getApiToken());
+  for (const [k, v] of Object.entries(params)) {
+    if (v) url.searchParams.set(k, v);
+  }
+  const resp = await fetch(url.toString());
+  if (!resp.ok) throw new Error(`Pappers API error ${resp.status}: ${await resp.text()}`);
+  return resp.json();
+}
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+var server = new McpServer({
+  name: "pappers-mcp-server",
+  version: "1.0.0"
+});
+server.tool(
+  "search-company",
+  "Search for French companies by name, NAF code, department, region or workforce range.",
+  {
+    q: z.string().describe("Search query (company name, SIREN, etc.)"),
+    code_naf: z.string().default("").describe('NAF code filter (e.g. "6201Z")'),
+    departement: z.string().default("").describe('Department number filter (e.g. "75")'),
+    region: z.string().default("").describe('Region filter (e.g. "Ile-de-France")'),
+    tranche_effectif: z.string().default("").describe("Workforce range filter"),
+    page: z.string().default("1").describe("Page number (default 1)"),
+    par_page: z.string().default("10").describe("Results per page (default 10, max 100)")
+  },
+  async (params) => {
+    const data = await pappers("/recherche", {
+      q: params.q,
+      code_naf: params.code_naf,
+      departement: params.departement,
+      region: params.region,
+      tranche_effectif: params.tranche_effectif,
+      page: params.page,
+      par_page: params.par_page,
+      champs_supplementaires: "sites_internet,telephone,email"
+    });
+    if (!data.resultats?.length) {
+      return textResult("Aucun resultat trouve.");
+    }
+    const lines = [`**${data.total} resultats** (page ${data.page})
+`];
+    for (const e of data.resultats) {
+      const parts = [`### ${e.nom_entreprise}`, `SIREN: ${e.siren}`];
+      if (e.siege?.siret) parts.push(`SIRET siege: ${e.siege.siret}`);
+      if (e.siege) {
+        const addr = [e.siege.adresse_ligne_1, e.siege.code_postal, e.siege.ville].filter(Boolean).join(" ");
+        if (addr) parts.push(`Adresse: ${addr}`);
+      }
+      if (e.code_naf) parts.push(`NAF: ${e.code_naf} - ${e.libelle_code_naf || ""}`);
+      if (e.tranche_effectif) parts.push(`Effectif: ${e.tranche_effectif}`);
+      if (e.dirigeants?.length) {
+        const dirs = e.dirigeants.map((d) => `${d.prenom || ""} ${d.nom || ""} (${d.qualite || ""})`.trim()).join(", ");
+        parts.push(`Dirigeants: ${dirs}`);
+      }
+      if (e.sites_internet?.length) {
+        parts.push(`Site web: ${e.sites_internet.map((s) => s.url).join(", ")}`);
+      }
+      if (e.telephone) parts.push(`Telephone: ${e.telephone}`);
+      if (e.email) parts.push(`Email: ${e.email}`);
+      lines.push(parts.join("\n"));
+    }
+    return textResult(lines.join("\n\n"));
+  }
+);
+server.tool(
+  "get-company",
+  "Get detailed information about a French company by SIREN or SIRET number.",
+  {
+    siren: z.string().default("").describe("SIREN number (9 digits)"),
+    siret: z.string().default("").describe("SIRET number (14 digits). Use either siren or siret.")
+  },
+  async (params) => {
+    if (!params.siren && !params.siret) {
+      return textResult("Erreur: vous devez fournir un SIREN ou un SIRET.");
+    }
+    const queryParams = {
+      champs_supplementaires: "sites_internet,telephone,email,lien_linkedin"
+    };
+    if (params.siret) {
+      queryParams.siret = params.siret;
+    } else {
+      queryParams.siren = params.siren;
+    }
+    const data = await pappers("/entreprise", queryParams);
+    const lines = [`# ${data.nom_entreprise}`];
+    lines.push(`**SIREN:** ${data.siren}`);
+    if (data.siege?.siret) lines.push(`**SIRET siege:** ${data.siege.siret}`);
+    if (data.forme_juridique) lines.push(`**Forme juridique:** ${data.forme_juridique}`);
+    if (data.date_creation_formate || data.date_creation) {
+      lines.push(`**Date de creation:** ${data.date_creation_formate || data.date_creation}`);
+    }
+    if (data.code_naf) {
+      lines.push(`**Code NAF:** ${data.code_naf} - ${data.libelle_code_naf || ""}`);
+    }
+    if (data.objet_social) lines.push(`**Objet social:** ${data.objet_social}`);
+    if (data.siege) {
+      const addr = [
+        data.siege.adresse_ligne_1,
+        data.siege.adresse_ligne_2,
+        data.siege.code_postal,
+        data.siege.ville,
+        data.siege.pays
+      ].filter(Boolean).join(" ");
+      if (addr) lines.push(`**Adresse:** ${addr}`);
+    }
+    if (data.tranche_effectif || data.effectif) {
+      lines.push(`**Effectif:** ${data.effectif || data.tranche_effectif}`);
+    }
+    if (data.capital_formate || data.capital) {
+      lines.push(`**Capital social:** ${data.capital_formate || `${data.capital} EUR`}`);
+    }
+    if (data.representants?.length) {
+      lines.push("\n**Dirigeants:**");
+      for (const d of data.representants) {
+        if (d.personne_morale && d.denomination) {
+          lines.push(`- ${d.denomination} (${d.qualite || "N/A"})`);
+        } else {
+          const name = d.nom_complet || `${d.prenom || ""} ${d.nom || ""}`.trim();
+          lines.push(`- ${name} (${d.qualite || "N/A"})`);
+        }
+      }
+    }
+    if (data.sites_internet?.length) {
+      lines.push(`
+**Site(s) web:** ${data.sites_internet.map((s) => s.url).join(", ")}`);
+    }
+    if (data.telephone) lines.push(`**T\xE9l\xE9phone:** ${data.telephone}`);
+    if (data.email) lines.push(`**Email:** ${data.email}`);
+    if (data.lien_linkedin) lines.push(`**LinkedIn:** ${data.lien_linkedin}`);
+    if (data.numero_tva_intracommunautaire) {
+      lines.push(`**N\xB0 TVA:** ${data.numero_tva_intracommunautaire}`);
+    }
+    if (data.greffe) lines.push(`**Greffe:** ${data.greffe}`);
+    if (data.statut_rcs) lines.push(`**Statut RCS:** ${data.statut_rcs}`);
+    return textResult(lines.join("\n"));
+  }
+);
+server.tool(
+  "get-dirigeants",
+  "Get the list of directors/officers of a French company by SIREN number.",
+  {
+    siren: z.string().describe("SIREN number (9 digits)")
+  },
+  async (params) => {
+    const data = await pappers("/entreprise", {
+      siren: params.siren,
+      champs_supplementaires: "lien_linkedin"
+    });
+    if (!data.representants?.length) {
+      return textResult(`Aucun dirigeant trouv\xE9 pour ${data.nom_entreprise} (${data.siren}).`);
+    }
+    const lines = [`# Dirigeants de ${data.nom_entreprise} (${data.siren})
+`];
+    for (const d of data.representants) {
+      if (d.personne_morale && d.denomination) {
+        const parts = [`### ${d.denomination}`];
+        if (d.siren) parts.push(`SIREN: ${d.siren}`);
+        if (d.qualite) parts.push(`Fonction: ${d.qualite}`);
+        lines.push(parts.join("\n"));
+      } else {
+        const name = d.nom_complet || `${d.prenom || ""} ${d.nom || ""}`.trim();
+        const parts = [`### ${name}`];
+        if (d.qualite) parts.push(`Fonction: ${d.qualite}`);
+        if (d.date_de_naissance_formate) parts.push(`Date de naissance: ${d.date_de_naissance_formate}`);
+        if (d.nationalite) parts.push(`Nationalit\xE9: ${d.nationalite}`);
+        lines.push(parts.join("\n"));
+      }
+    }
+    if (data.lien_linkedin) lines.push(`
+**LinkedIn entreprise:** ${data.lien_linkedin}`);
+    return textResult(lines.join("\n\n"));
+  }
+);
+server.tool(
+  "get-finances",
+  "Get financial data (revenue, profit, workforce) of a French company by SIREN number.",
+  {
+    siren: z.string().describe("SIREN number (9 digits)")
+  },
+  async (params) => {
+    const data = await pappers("/entreprise", {
+      siren: params.siren,
+      champs_supplementaires: "finances"
+    });
+    if (!data.finances?.length) {
+      return textResult(
+        `Aucune donnee financiere trouvee pour ${data.nom_entreprise} (${data.siren}).`
+      );
+    }
+    const lines = [`# Donnees financieres de ${data.nom_entreprise} (${data.siren})
+`];
+    for (const f of data.finances) {
+      const year = f.annee || f.date_cloture_formate || f.date_cloture || "N/A";
+      const parts = [`### Exercice ${year}`];
+      if (f.date_cloture_formate) parts.push(`Cloture: ${f.date_cloture_formate}`);
+      if (f.duree_exercice) parts.push(`Duree: ${f.duree_exercice} mois`);
+      if (f.chiffre_affaires != null) {
+        parts.push(`Chiffre d'affaires: ${formatCurrency(f.chiffre_affaires)}`);
+      }
+      if (f.resultat != null) parts.push(`Resultat: ${formatCurrency(f.resultat)}`);
+      if (f.resultat_net != null) parts.push(`Resultat net: ${formatCurrency(f.resultat_net)}`);
+      if (f.resultat_exploitation != null) {
+        parts.push(`Resultat d'exploitation: ${formatCurrency(f.resultat_exploitation)}`);
+      }
+      if (f.excedent_brut_exploitation != null) {
+        parts.push(`EBE: ${formatCurrency(f.excedent_brut_exploitation)}`);
+      }
+      if (f.marge_brute != null) parts.push(`Marge brute: ${formatCurrency(f.marge_brute)}`);
+      if (f.effectif != null) parts.push(`Effectif: ${f.effectif}`);
+      if (f.capitaux_propres != null) {
+        parts.push(`Capitaux propres: ${formatCurrency(f.capitaux_propres)}`);
+      }
+      if (f.total_bilan != null) parts.push(`Total bilan: ${formatCurrency(f.total_bilan)}`);
+      lines.push(parts.join("\n"));
+    }
+    return textResult(lines.join("\n\n"));
+  }
+);
+server.tool(
+  "search-dirigeant",
+  "Search for company directors/officers by name.",
+  {
+    q: z.string().describe("Director name to search for"),
+    page: z.string().default("1").describe("Page number (default 1)"),
+    par_page: z.string().default("10").describe("Results per page (default 10)")
+  },
+  async (params) => {
+    const data = await pappers("/recherche-dirigeants", {
+      q: params.q,
+      page: params.page,
+      par_page: params.par_page
+    });
+    if (!data.resultats?.length) {
+      return textResult("Aucun dirigeant trouve.");
+    }
+    const lines = [`**${data.total} resultats** (page ${data.page})
+`];
+    for (const d of data.resultats) {
+      const name = `${d.prenom || ""} ${d.nom || ""}`.trim();
+      const parts = [`### ${name}`];
+      if (d.date_de_naissance_formate || d.date_de_naissance) {
+        parts.push(
+          `Date de naissance: ${d.date_de_naissance_formate || d.date_de_naissance}`
+        );
+      }
+      if (d.nationalite) parts.push(`Nationalite: ${d.nationalite}`);
+      if (d.entreprises?.length) {
+        parts.push("Entreprises:");
+        for (const e of d.entreprises) {
+          parts.push(`- ${e.nom_entreprise || "N/A"} (SIREN: ${e.siren || "N/A"}) \u2014 ${e.qualite || "N/A"}`);
+        }
+      }
+      lines.push(parts.join("\n"));
+    }
+    return textResult(lines.join("\n\n"));
+  }
+);
+function formatCurrency(value) {
+  return new Intl.NumberFormat("fr-FR", { style: "currency", currency: "EUR", maximumFractionDigits: 0 }).format(value);
+}
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@mnicole-dev/pappers-mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for the Pappers API (French company information)",
+  "type": "module",
+  "bin": {
+    "pappers-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --out-dir dist --clean",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mnicole90/pappers-mcp-server.git"
+  },
+  "homepage": "https://github.com/mnicole90/pappers-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/mnicole90/pappers-mcp-server/issues"
+  },
+  "author": "Maxime Nicole <maxime@kodesaas.com> (https://kodesaas.com)",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "pappers",
+    "entreprise",
+    "siren",
+    "siret",
+    "french-companies",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  }
+}