@perenia/mcp

MCP server for the Perenia Partner API — search and analyze ~3.5M French companies from Claude, Cursor, or any MCP client. Runs locally over stdio; every call goes to https://api.perenia.ai with your API key, so your plan's rate limits and quotas apply as usual.

Setup

You need a Perenia Partner API key (pk_live_…).

Claude Code

claude mcp add perenia --env PERENIA_API_KEY=pk_live_… -- npx -y @perenia/mcp

Claude Desktop / other clients (claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "perenia": {
      "command": "npx",
      "args": ["-y", "@perenia/mcp"],
      "env": { "PERENIA_API_KEY": "pk_live_…" }
    }
  }
}

Optional: PERENIA_API_URL overrides the API base URL (for local development against a dev instance).

Tools

| Tool | What it does | |---|---| | search_companies | Text + filtered search (location, NAF activity, size, financials, financial-score grade, decision-maker age, geo radius). Compact summaries, paginated — or, with columns, rows holding exactly the requested columns (same ids as the web table's templates and CSV export). include_list_ids restricts the search to your lists' members, exclude_list_ids drops them (dedupe against a pipeline; exclusion wins on overlap; bound key), exclude_sirens drops individual companies. sort takes <columnId>:asc|desc for any column list_columns marks sortable (e.g. turnover:desc). | | get_companies | Batch lookup of up to 100 SIRENs in one call, in the order given, as summaries or columns rows; reports the SIRENs not found. | | open_in_perenia | Turns the same filters as search_companies into the URL of that search in the web app — the link to hand to a person. | | list_columns | The column catalogue for columns, grouped, with each column's kind, whether it sorts (sortable → sort: "<id>:asc|desc" in search_companies) and fields. No quota cost. | | get_usage | Today's quota for your key (used / limit / remaining / reset) and the per-minute rate limit. Every other tool result already ends with the same quota figures. | | get_lists · get_list_contents · create_list · add_to_list | Your lists in the Perenia app: read them (member SIRENs in display order), create one, add companies by SIREN (idempotent, unknown SIRENs reported). Need a key bound to your Perenia user with the lists scope — ask your Perenia contact; an unbound key gets key_not_bound. |

Every result carries perenia_url per company (the company page in the app). PERENIA_APP_URL overrides the app origin those links use. | get_company | Full profile by SIREN, including multi-year financial history. | | get_company_officers | Officer roster (names and roles — no personal data). | | get_network_neighbours | Companies sharing an officer network (holdings, sister companies). | | list_facet_values | Valid values + company counts for a categorical field, optionally scoped by filters — use it to discover filter values or get distributions. |

Data refreshes daily. Errors carry the API's error code; a 429 includes the Retry-After hint (per-minute rate limit or daily quota — see your contract).

Development (this repo)

npm -w @perenia/mcp test         # in-memory MCP client ↔ server against an API stub
npm -w @perenia/mcp run build    # emit dist/
PERENIA_API_KEY=… npm -w @perenia/mcp run dev

Publishing: npm publish -w @perenia/mcp (runs build via prepublishOnly).