ZennoPoster MCP

English | Русский

Conectando os servidores MCP do ZennoPoster/ProjectMaker ao seu próprio cliente de LLM

Os servidores MCP são publicados como binários win-x64 autocontidos via GitHub Releases no repositório compartilhado https://github.com/ZennoLab/zennoposter-mcp/releases. Cada servidor tem sua própria linha de releases (seu próprio prefixo de tag):

• ProjectMaker (editor) — tags mcp-projectmaker-v*, arquivo MCP.ProjectMaker-v*-win-x64.zip
• Instance (controle de navegador, montagem dupla) — tags mcp-instance-v*, arquivo MCP.Instance-v*-win-x64.zip
• ZennoPoster (executor de tarefas) — tags mcp-zennoposter-v*, arquivo MCP.ZennoPoster-v*-win-x64.zip
• Android (dispositivo ZennoDroid) — tags mcp-android-v*, arquivo MCP.Android-v*-win-x64.zip

A documentação da PublicApi (o contrato OpenAPI renderizado com Redoc, o guia do integrador, códigos de erro, política de versionamento) está em https://zennolab.github.io/zennoposter-mcp/ (as páginas são publicadas a partir da pasta docs/ deste repositório).

Esses servidores conversam com ZennoPoster 7.9.2 e mais recentes e com ZennoDroid 2.6.1 e mais recentes. MCP.Instance se aplica apenas ao ZennoPoster e MCP.Android apenas ao ZennoDroid; MCP.ProjectMaker e MCP.ZennoPoster se aplicam a ambos. Qual versão do servidor acompanha qual produto e versão de contrato: https://zennolab.github.io/zennoposter-mcp/compatibility.html.

Botões de instalação para Cursor e VS Code e os comandos do Claude Code para cada servidor: https://zennolab.github.io/zennoposter-mcp/install.html.

O modelo: sua própria instância MCP com sua própria chave

O produto em si inicia servidores MCP internos para seu chat de IA integrado — eles ficam na faixa de portas internas 6107–6113 (no ZennoDroid tudo é deslocado por +10), recebem uma chave de serviço de privilégio mínimo do host e ignoram o cabeçalho Authorization de requisições recebidas. Isso é infraestrutura interna: conectar-se a ela de fora não é suportado (as permissões lá são definidas pela chave de serviço, não pelas suas), e suas portas não devem estar ocupadas — um processo estranho em uma porta dessa faixa impede o servidor integrado de iniciar (o produto registra um erro, mas sua pilha de IA fica sem esse servidor).

Para seu próprio cliente de LLM, você executa uma cópia separada do servidor MCP do pacote público: ele escuta na faixa de portas públicas 6207–6211 e conversa com o mesmo produto PublicApi (:5299 ProjectMaker / :5300 ZennoPoster), mas com sua ApiKey — com os escopos/níveis que você escolheu ao emitir a chave. Ambas as cópias rodam lado a lado sem interferir uma na outra.

No ZennoDroid, os dois servidores que atendem ambos os produtos escutam +10 mais alto — MCP.ProjectMaker na 6217, MCP.ZennoPoster na 6220 — o mesmo deslocamento que o produto aplica à sua faixa interna. Dessa forma, uma máquina com ambos os produtos instalados pode executar ambos os conjuntos ao mesmo tempo. MCP.Android existe apenas no ZennoDroid e mantém 6211: nada no ZennoPoster a ocupa.

Portas padrão (definidas no appsettings.json ao lado do executável):

Servidor	Porta	Conversa com	Chave na configuração
MCP.ProjectMaker	6207	PM PublicApi :5299	ProjectMaker:ApiKey
MCP.Instance (Target=projectmaker)	6208	PM PublicApi :5299	Instance:ApiKey
MCP.Instance (Target=zennoposter)	6209 (convenção, definida explicitamente)	ZP PublicApi :5300	Instance:ApiKey
MCP.ZennoPoster	6210	ZP PublicApi :5300	ZennoPoster:ApiKey
MCP.Android (ZennoDroid, dispositivo editor)	6211	ZDroid PM PublicApi :5309	Android:ApiKey
MCP.Android (ZennoDroid, dispositivos de tarefa)	6212 (convenção, definida explicitamente)	ZDroid ZP PublicApi :5310	Android:ApiKey

A API do produto que esses servidores chamam escuta em portas diferentes nos dois produtos:

Aplicação	ZennoPoster	ZennoDroid
ProjectMaker	5299	5309
ZennoPoster	5300	5310

Os padrões acima e os exemplos abaixo são para ZennoPoster. No ZennoDroid, cada servidor precisa tanto de sua porta de escuta quanto de seu BaseUrl definidos explicitamente:

Servidor	Porta	Conversa com	Chave na configuração
MCP.ProjectMaker	6217 (definida explicitamente)	ZDroid PM PublicApi :5309	ProjectMaker:ApiKey
MCP.ZennoPoster	6220 (definida explicitamente)	ZDroid ZP PublicApi :5310	ZennoPoster:ApiKey
MCP.Android (dispositivo editor)	6211	ZDroid PM PublicApi :5309	Android:ApiKey
MCP.Android (dispositivos de tarefa)	6212 (definida explicitamente)	ZDroid ZP PublicApi :5310	Android:ApiKey

Tudo pode ser sobrescrito através da configuração padrão do ASP.NET Core: o appsettings.json ao lado do executável, variáveis de ambiente (ASPNETCORE_URLS, ProjectMaker__ApiKey, …) ou argumentos de linha de comando (--urls, --ProjectMaker:ApiKey=…, …) — argumentos sobrescrevem variáveis de ambiente, variáveis de ambiente sobrescrevem appsettings.json.

1. Baixe o servidor que você precisa

Na página de releases, encontre o release mais recente do servidor que você precisa (pelo prefixo de tag), baixe seu *-win-x64.zip e descompacte-o em qualquer pasta. Cada arquivo é um único .exe autocontido + appsettings.json; nenhum runtime adicional do .NET é necessário.

2. Emita uma ApiKey

No ProjectMaker: Configurações → API Keys → Adicionar — a caixa de diálogo "Adicionar chave de API" abre:

1. Defina um Label (um nome de chave arbitrário, para distinguir chaves na lista).
2. Escolha o Max tier (o mínimo suficiente para suas tarefas — T0 para somente leitura, mais alto para operações de mutação).
3. Marque os Scopes que você precisa (apenas *:read estão marcados por padrão; adicione outros conforme necessário).
4. Confirme — a chave bruta é mostrada uma vez; copie-a para um local seguro imediatamente.

Mais sobre escopos/níveis — security-model.md.

3. Execute o servidor com sua chave

A chave é definida na configuração do próprio servidor MCP (não nos cabeçalhos do cliente MCP — o servidor aceita conexões apenas de loopback e não lê o cabeçalho Authorization de requisições recebidas). A maneira mais simples é colocar a chave em ApiKey no appsettings.json ao lado do executável e iniciar sem argumentos; ou passá-la via variáveis de ambiente / argumentos:

# ProjectMaker (editor): 6207 -> :5299
.\ZennoLab.AI.MCP.ProjectMaker.exe --ProjectMaker:ApiKey=zp_xxx

# Instance for the editor (PM browser): 6208 -> :5299
.\ZennoLab.AI.MCP.Instance.exe --Instance:ApiKey=zp_xxx

# Instance for the runner — a SECOND copy of the same exe: the port and the Target/BaseUrl pair are set explicitly
.\ZennoLab.AI.MCP.Instance.exe --urls http://localhost:6209 `
  --Instance:Target=zennoposter --Instance:BaseUrl=http://localhost:5300/api/v1 `
  --Instance:ApiKey=zp_xxx

# ZennoPoster (runner tasks/sessions): 6210 -> :5300
.\ZennoLab.AI.MCP.ZennoPoster.exe --ZennoPoster:ApiKey=zp_xxx

# Android (the device attached to ProjectMaker): 6211 -> :5309
.\ZennoLab.AI.MCP.Android.exe --Android:ApiKey=zp_xxx

# Android for the runner — a SECOND copy of the same exe, for the devices of running tasks
.\ZennoLab.AI.MCP.Android.exe --urls http://localhost:6212 `
  --Android:BaseUrl=http://localhost:5310/api/v1 --Android:ApiKey=zp_xxx

MCP.Android monta duas vezes pela mesma razão que MCP.Instance faz no ZennoPoster: o domínio Android é servido tanto pela PublicApi do ProjectMaker (o dispositivo que você vê no editor) quanto pela do executor (os dispositivos que suas tarefas estão dirigindo). Diferente de MCP.Instance, ele não tem Target, então as duas cópias diferem apenas por --urls e BaseUrl.

No ZennoDroid, os mesmos dois executáveis são iniciados nas portas deslocadas e apontados para a API do ZennoDroid:

# ProjectMaker on ZennoDroid: 6217 -> :5309
.\ZennoLab.AI.MCP.ProjectMaker.exe --urls http://localhost:6217 `
  --ProjectMaker:BaseUrl=http://localhost:5309/api/v1 --ProjectMaker:ApiKey=zp_xxx

# ZennoPoster tasks on ZennoDroid: 6220 -> :5310
.\ZennoLab.AI.MCP.ZennoPoster.exe --urls http://localhost:6220 `
  --ZennoPoster:BaseUrl=http://localhost:5310/api/v1 --ZennoPoster:ApiKey=zp_xxx

Nota importante sobre as duas cópias de MCP.Instance: para o servidor Instance, Target (quais instruções ele serve à IA — sobre ProjectMaker ou sobre ZennoPoster) e BaseUrl (para onde as requisições HTTP realmente vão) são configurados apenas juntos, como um par, e não estão vinculados no código (Target=projectmaker → BaseUrl na PM PublicApi :5299, Target=zennoposter → BaseUrl na ZP PublicApi :5300). Na inicialização, o servidor faz uma verificação de melhor esforço via /capabilities do host de destino e registra um aviso em caso de incompatibilidade, mas se o host de destino estiver inacessível na inicialização, a verificação é silenciosamente ignorada — uma incompatibilidade então não é detectada, e a IA recebe instruções sobre um host enquanto as requisições vão para outro.

4. Configure seu cliente de LLM

Um fragmento de configuração pronto (o formato corresponde ao .mcp.json do Claude Code; use o equivalente para seu cliente MCP, se necessário):

{
  "servers": {
    "projectmaker": {
      "type": "http",
      "url": "http://localhost:6207"
    },
    "instance-pm": {
      "type": "http",
      "url": "http://localhost:6208"
    },
    "instance-zp": {
      "type": "http",
      "url": "http://localhost:6209"
    },
    "zennoposter": {
      "type": "http",
      "url": "http://localhost:6210"
    }
  }
}

No ZennoDroid, as entradas são estas — nomes diferentes, para que ambos os produtos possam ser configurados em um único cliente, e sem montagem instance-*, que o ZennoDroid não tem:

{
  "servers": {
    "projectmaker-droid": {
      "type": "http",
      "url": "http://localhost:6217"
    },
    "zennodroid": {
      "type": "http",
      "url": "http://localhost:6220"
    },
    "android-pm": {
      "type": "http",
      "url": "http://localhost:6211"
    },
    "android-zd": {
      "type": "http",
      "url": "http://localhost:6212"
    }
  }
}

Nenhuma autorização é necessária nesta etapa: os servidores MCP escutam apenas em loopback, e as permissões são definidas pela chave com a qual o próprio servidor foi iniciado (passo 3).

5. Verifique a conexão

Com qualquer cliente MCP (ou HTTP simples), chame um método seguro somente leitura e certifique-se de que ele responda 200 OK com os dados esperados — por exemplo, get_product_version/ping no servidor que você precisa. Se a chave for inválida ou faltar um escopo/nível, o servidor retorna um erro estruturado (401 unauthorized / 403 forbidden com campos required/current), não uma falha silenciosa.

Alterando portas

Cada servidor tem duas portas: a que ele escuta para seu cliente de LLM e a porta da API do produto que ele chama.

Porta de escuta. Qualquer uma das três, argumentos vencendo o ambiente, ambiente vencendo o arquivo:

.\ZennoLab.AI.MCP.ProjectMaker.exe --urls http://localhost:7207

$env:ASPNETCORE_URLS = "http://localhost:7207"
.\ZennoLab.AI.MCP.ProjectMaker.exe

ou "Urls": "http://localhost:7207" no appsettings.json ao lado do executável. Após mover uma porta de escuta, atualize a URL correspondente na configuração do cliente do passo 4.

Fique longe de 6107–6113 (6117–6123 no ZennoDroid): essas pertencem aos servidores integrados do produto, e um processo estranho em uma delas impede o servidor integrado de iniciar.

Porta da API do produto. Defina o BaseUrl da seção própria desse servidor — é isso que você altera no ZennoDroid:

# ProjectMaker API on 5309 instead of 5299
.\ZennoLab.AI.MCP.ProjectMaker.exe --ProjectMaker:BaseUrl=http://localhost:5309/api/v1 --ProjectMaker:ApiKey=zp_xxx

# ZennoPoster API on 5310 instead of 5300
.\ZennoLab.AI.MCP.ZennoPoster.exe --ZennoPoster:BaseUrl=http://localhost:5310/api/v1 --ZennoPoster:ApiKey=zp_xxx

A seção é nomeada após o servidor: ProjectMaker, Instance, ZennoPoster, Android. Versões até 0.3.0 de MCP.ProjectMaker e MCP.ZennoPoster usavam NeuroBot e ZennoPosterApi; esses nomes ainda funcionam em versões posteriores e o servidor registra um aviso na inicialização.

Licença

Os arquivos neste repositório (documentação e a especificação OpenAPI) são licenciados sob a MIT License. Os binários do servidor MCP na página de Releases são proprietários; seus termos estão em TERMS.md.