# mcp-french-company-data

An [MCP](https://modelcontextprotocol.io) server that lets Claude, Cursor or any MCP client look up
**French companies in official open data**: identity and key figures from the
*API Recherche d'entreprises*, and legal announcements (insolvency, deregistration, accounts
filings, changes) from the **BODACC**, the official gazette of commercial notices.

No API key, no account, read-only. Python, official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) (v2), stdio transport.

## Tools

| Tool | What it does | Source |
|---|---|---|
| `search_companies` | Find companies by name, brand, address words, SIREN or SIRET. Optional postal code, active-only filter, 1–25 results. | Recherche d'entreprises |
| `get_company` | Full public profile from a SIREN or SIRET: status, legal form, NAF code, size, head office, VAT number, latest published revenue and net income, labels (RGE, ESS, Qualiopi...). | Recherche d'entreprises |
| `get_bodacc_announcements` | Latest BODACC notices for a company, newest first, optional category filter (`collective` = insolvency, `radiation`, `dpc` = accounts, `modification`, `vente`...). Flags insolvency proceedings in the results. | BODACC (DILA) |

All tools are annotated `readOnlyHint: true`. SIREN/SIRET inputs are checked (Luhn key) before any
network call, and every answer carries its source and licence.

## Installation

Requires Python 3.10+.

```bash
git clone https://github.com/Kamelyoul/mcp-french-company-data
cd mcp-french-company-data
python -m venv .venv
# Windows: .venv\Scripts\activate    macOS/Linux: source .venv/bin/activate
pip install -e ".[test]"
python examples/demo_client.py --list   # starts the server over stdio and lists the tools
```

Or run it without cloning, with [uv](https://docs.astral.sh/uv/):

```bash
uvx --from git+https://github.com/Kamelyoul/mcp-french-company-data mcp-french-company-data
```

## Configuration

### Claude Desktop

Edit `claude_desktop_config.json` (Settings > Developer > Edit Config), then restart Claude Desktop.

With uv (nothing to install by hand):

```json
{
  "mcpServers": {
    "french-company-data": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Kamelyoul/mcp-french-company-data", "mcp-french-company-data"]
    }
  }
}
```

With the virtual environment created above (use the absolute path of your clone):

```json
{
  "mcpServers": {
    "french-company-data": {
      "command": "C:\\path\\to\\mcp-french-company-data\\.venv\\Scripts\\python.exe",
      "args": ["-m", "french_company_data"]
    }
  }
}
```

On macOS/Linux the command is `/path/to/mcp-french-company-data/.venv/bin/python`.

### Cursor

Same block in `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project):

```json
{
  "mcpServers": {
    "french-company-data": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Kamelyoul/mcp-french-company-data", "mcp-french-company-data"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add french-company-data -- uvx --from git+https://github.com/Kamelyoul/mcp-french-company-data mcp-french-company-data
```

## Example prompts

- *"Find the SIREN of Danone and give me its head office address and VAT number."*
- *"Is the company with SIRET 552 032 534 00703 still active? What was its last published revenue?"*
- *"Check the BODACC for SIREN 552032534: any insolvency proceedings or deregistration?"*
- *"Here are 10 supplier SIRENs. For each one, tell me if there is an insolvency notice in the BODACC."*

Sample output of `get_company` (real call, 7 October 2026, abridged):

```json
{
  "company": {
    "siren": "552032534",
    "name": "DANONE",
    "status": "active",
    "legal_form": "SA with board of directors (5599)",
    "activity_code_naf": "70.10Z",
    "head_office": {"siret": "55203253400703", "address": "59-61 RUE LA FAYETTE 75009 PARIS"},
    "vat_number": "FR27552032534",
    "latest_published_accounts": {"year": "2025", "revenue_eur": 27376000000, "net_income_eur": 2100000000},
    "page": "https://annuaire-entreprises.data.gouv.fr/entreprise/552032534"
  },
  "source": "Source: API Recherche d'entreprises (DINUM, annuaire-entreprises.data.gouv.fr), INSEE Sirene / RNE data, Licence Ouverte 2.0."
}
```

`python examples/demo_client.py` runs the three tools against the live APIs (3 requests).

## Limits (read before relying on it)

- **Rate limits are respected, not bypassed.** Recherche d'entreprises allows at most
  7 requests/second per IP (and 30/s per network); the server sends at most **4/s**. BODACC on
  OpenDataSoft has an anonymous daily quota (20,000 calls/day observed in its `X-RateLimit-*`
  headers); the server sends at most **2/s**. On HTTP 429 it waits once if `Retry-After` is
  ≤ 10 s, otherwise it returns a clear "rate limit reached" error to the model. Identical requests
  are cached in memory for 5 minutes. Requests carry a descriptive `User-Agent`, as the API asks.
- **Not the full Sirene database.** Companies that opted out of public listing
  (*non-diffusibles*) are not returned, by design of the API.
- **Freshness.** Data may lag the official registries by a few days. BODACC entries for sole
  proprietors are sometimes not linked to a SIREN and can be missed.
- **No personal data on purpose.** Company officers (names, birth dates) are not requested from the
  API. Sole proprietorships are named after a person: treat those results as personal data (GDPR).
- **Not legal or financial advice.** For a decision (credit, claim filing deadline), open the
  official notice: every BODACC result includes its `bodacc.fr` URL.
- The BODACC OpenDataSoft endpoint is the one documented on data.gouv.fr today; DILA may move it.
  The URL is a single constant in `sources.py`.

## Tests

```bash
pytest                    # 27 offline tests: simulated HTTP + MCP client, plus a real stdio launch
LIVE=1 pytest -m live     # 1 end-to-end test against the real APIs (3 requests)
```

Offline tests use recorded API responses (`tests/fixtures/`, re-recorded with
`python tests/record_fixtures.py`). The insolvency example is a real announcement whose company
identity was replaced by a fictitious one (`SAMPLE FLOORING SARL`, SIREN 732829320).

## Data sources and attribution

- **API Recherche d'entreprises**, operated by DINUM for
  [annuaire-entreprises.data.gouv.fr](https://annuaire-entreprises.data.gouv.fr), built on INSEE
  Sirene and INPI RNE data. Documentation: <https://recherche-entreprises.api.gouv.fr/docs/>.
  Data under [Licence Ouverte / Open Licence 2.0](https://www.etalab.gouv.fr/licence-ouverte-open-licence/).
- **BODACC** (Bulletin officiel des annonces civiles et commerciales), published by DILA, served at
  <https://bodacc-datadila.opendatasoft.com>. Data under
  [Licence Ouverte / Open Licence 2.0](https://www.etalab.gouv.fr/licence-ouverte-open-licence/).

This project is not affiliated with, or endorsed by, DINUM, INSEE, INPI or DILA.

## Custom MCP servers

Need the same thing on your own database, internal API or SaaS tools (with authentication,
tests and deployment)? Open an issue describing your use case.

## License

MIT (code). Data remains under its own licence, see above.