Zefix Search

Pesquisa de empresas no Índice Central de Nomes Comerciais Suíço (zefix.ch)

Documentação

Zefix MCP

⚠️ Não oficial servidor MCP para zefix.ch – Índice Central de Nomes de Empresas da Suíça.
Este projeto não é afiliado ou endossado pelo Departamento Federal de Justiça e Polícia (DFJP) - Escritório Federal de Justiça (EFJ), que desenvolve e mantém o zefix.ch.

Recursos e Casos de Uso

Permite que seu assistente de IA pesquise empresas incorporadas na Suíça pelo nome ou UID (CHE-nnn.nnn.nnn) com filtros opcionais por cantão de incorporação, forma jurídica, localização, nomes anteriores, etc. (imita todos os filtros da interface gráfica do Zefix).
Equipa seu assistente de IA com todos os detalhes da empresa disponíveis no Zefix (nomes comerciais e identificadores, objetivo, endereço, auditores, histórico de alterações, capital, nomes de representantes legais, fusões e aquisições) para construir fluxos de automação adicionais ou responder perguntas específicas de negócios.

Perguntas de exemplo que o MCP pode responder

Consulta de empresas

"Descubra se o Google tem uma entidade legal na Suíça e mostre-me o endereço registrado."
"Was ist der vollständige rechtliche Name und die UID des Unternehmens, das als Migros bekannt ist?"
"Recherche le CHE-169.865.482 et dis-moi tout ce que tu sais à son sujet."

Filtragem e descoberta

"Liste todas as empresas Treuhand ativas com sede no cantão de Schaffhausen."
"Finde Einzelunternehmen im Bereich Malerei, die irgendwo in der Grossregion Zürich eingetragen sind."
"Dresse une liste des adresses et des représentants légaux de toutes les banques en Romandie."

Histórico e alterações

"Qual é o novo nome da empresa anteriormente conhecida como 'SwissAir'?"
"Zeig mir die vollständige Namens- und Eigentümergeschichte von Credit Suisse."
"Y a-t-il des entreprises qui ont repris ou fusionné avec UBS AG ?"

Due diligence e pesquisa

"Quem está listado como auditor do Zurich Insurance Group?"
"Ich stehe kurz vor der Unterzeichnung eines Vertrags mit Hans Müller als Vertreter von Lindt & Sprüngli – ist er dazu bevollmächtigt?"
"Vérifie que Bollinger est une entreprise active spécialisée dans la plomberie, et dis-moi depuis combien de temps elle existe et quel est son capital enregistré."

Requisitos

Aplicativo host MCP (Claude, LLM Studio, VSCode+GHCP/Cline, Cursor, Dive, LibreChat, DeepChat, Chainlit etc.)
LLM que suporte chamada de ferramentas (GPT-4.1+ Claude Sonnet/Opus, Gemini, Llama 3.1+, Qwen3.5, etc.)
(opcional) Node.js 24+ (para desenvolvimento ou execução local sem npx)

Instalação

Como extensão do Claude Desktop (mais fácil)

Vá para a página de Releases e baixe o arquivo zefix.mcpb mais recente.
Clique duas vezes nele — o Claude Desktop abre automaticamente.
Clique em Instalar.

Reinicie o Claude Desktop se você não vir a ferramenta zefix na lista de ferramentas disponíveis.

Via npx (recomendado para todos os outros hosts MCP)

Adicione à configuração do seu host MCP:

{
  "mcpServers": {
    "zefix": {
      "command": "npx",
      "args": ["-y", "zefix-mcp-unofficial"]
    }
  }
}

O npx baixa, armazena em cache e executa o pacote automaticamente. Nenhuma instalação local é necessária.

A partir do código-fonte

git clone https://github.com/your-org/zefix-mcp-unofficial.git
cd zefix-mcp-unofficial
npm install
npm run build

Em seguida, adicione esta seção ao arquivo de configuração do seu aplicativo host MCP (a sintaxe pode variar, consulte a documentação do seu aplicativo host MCP):

{
  "mcpServers": {
    "zefix": {
      "command": "node",
      "args": ["/absolute/path/to/zefix-mcp-unofficial/dist/index.js"]
    }
  }
}

Referência da ferramenta

`get_companies`

Pesquise no registro Zefix. Todos os parâmetros, exceto name_or_uid, são opcionais.

Parâmetro	Tipo	Descrição
`name_or_uid`	string	Nome da empresa ou UID (`CHE-nnn.nnn.nnn`).
`language_key`	string	Idioma da resposta: `en`, `de`, `fr`, `it`. Padrão: `en`.
`cantons`	string[]	Filtrar por códigos de cantão, ex.: `["ZH", "BE"]`.
`locations`	string[]	Filtrar por cidades de sede legal, ex.: `["Zurich", "Bern"]`.
`legalForms`	string[]	Filtrar por forma jurídica, ex.: `["AG", "GmbH"]`.
`exactSearch`	boolean	Pesquisar a partir do início do nome (padrão: `true`). Defina `false` para pesquisa de substring/curinga (`*`).
`phoneticSearch`	boolean	Ativar correspondência fonética/aproximada.
`includeDeleted`	boolean	Incluir empresas canceladas (padrão: `false`).
`includeFormerNames`	boolean	Pesquisar também nomes anteriores de empresas (padrão: `false`).

Dicas:

Se você souber o UID, use-o — ele retornará o resultado mais preciso com detalhes completos.
Se exactSearch: true não retornar resultados, tente novamente com a combinação de exactSearch: false e phoneticSearch: true.
Os resultados são retornados em formato YAML, com nível de detalhe dependendo da quantidade de empresas encontradas:
- 1 resultado → detalhes completos, incluindo histórico de publicação SOGC;
- 2–10 → resumos detalhados, mas sem histórico completo e lista de representantes legais;
- 11+ → apenas lista de nome/UID/status.
Os resultados são limitados a 100 itens.
O servidor se comunica via stdio (transporte padrão MCP) — ele não imprimirá nada no terminal quando executado diretamente.
Quando o servidor MCP consulta a API REST do Zefix em https://www.zefix.ch/ZefixREST/api/v1/ (pública, sem autenticação necessária), ele envia User-Agent: zefix-mcp-unofficial para transparência. Você pode querer alterar o uf se estiver usando este MCP como parte de sua solução maior.

Desenvolvimento e Depuração

Compilação

npm run build
# Compiled output goes to dist/index.js

Inspeção

Use o MCP Inspector para chamar ferramentas interativamente e inspecionar respostas:

npx @modelcontextprotocol/inspector node dist/index.js

A primeira execução solicitará a instalação do @modelcontextprotocol/inspector. Após a inicialização, abra a URL mostrada no terminal (geralmente http://localhost:5173) para acessar a interface do inspector.

Fluxo de trabalho:

Selecione a ferramenta get_companies no painel esquerdo.
Preencha os parâmetros (ex.: name_or_uid: "Berg Digital").
Clique em Executar e inspecione a resposta bruta.

Publicando um novo release

Enviar uma tag v* aciona o fluxo de trabalho de release do GitHub Actions, que executa dois jobs em paralelo:

Job	O que faz	Onde chega
Publicar no npm	`npm run build`, `npm publish`	npmjs.com
Publicar plugin Claude	`npm run build`, `npx @anthropic-ai/mcpb pack`, envia o asset `.mcpb`	GitHub Releases

# 1. Bump version in BOTH files (npm will reject publishing over an existing version):
#    - package.json  → "version": "x.y.z"
#    - manifest.json → "version": "x.y.z"

# 2. Commit, tag, push — the tag MUST point to the version-bump commit:
git add package.json manifest.json
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push && git push --tags

⚠️ Erro comum: criar a tag antes de editar package.json/manifest.json. A CI publica qualquer string de versão presente em package.json no commit da tag — o nome da tag em si é ignorado pelo npm. Se você marcou cedo demais, mova a tag para o commit correto:
git tag -d vX.Y.Z                   # exclui a tag local
git push origin :refs/tags/vX.Y.Z   # exclui a tag remota
# edite package.json + manifest.json, depois:
git add package.json manifest.json
git commit -m "chore: release vX.Y.Z"
git tag vX.Y.Z
git push && git push --tags

Configuração inicial (única vez):

token npm: crie um Access token em npmjs.com → adicione-o como Repository secret chamado NPM_TOKEN em GitHub → Settings → Secrets and variables → Actions; a validade do token é de 90 dias (máximo) — atualize regularmente.

GitHub releases: nenhuma configuração extra é necessária — o fluxo de trabalho usa o GITHUB_TOKEN integrado com permissão contents: write

Licença

MIT.