---
title: "O Angular CLI MCP server: setup, tools e como conectar no seu assistente de IA"
description: "Como configurar o Angular CLI MCP server: o comando exato pra subir, o formato da config do client, as tools que ele expõe e como conectar no Claude Code, no Cursor e no VS Code."
deck: "O Angular CLI traz um MCP server de dev-time que entrega tools com contexto de Angular pro seu assistente de IA. Você sobe ele com `ng mcp`, ou aponta um client pra `npx -y @angular/cli mcp`. A [página oficial](https://angular.dev/ai/mcp) ainda chama o servidor de experimental e expõe seis tools padrão, mais um grupo atrás do `--experimental-tool`, num CLI que recomenda a v20 ou mais nova."
author: "André Ramos"
url: "https://andreramos.dev/pt/angular/angular-mcp-server-setup/"
lang: "pt-BR"
type: "article"
---

# O Angular CLI MCP server: setup, tools e como conectar no seu assistente de IA

> O Angular CLI traz um MCP server de dev-time que entrega tools com contexto de Angular pro seu assistente de IA. Você sobe ele com `ng mcp`, ou aponta um client pra `npx -y @angular/cli mcp`. A [página oficial](https://angular.dev/ai/mcp) ainda chama o servidor de experimental e expõe seis tools padrão, mais um grupo atrás do `--experimental-tool`, num CLI que recomenda a v20 ou mais nova.

## O que o servidor é de fato

O Angular CLI MCP server é um processo de dev-time. Ele roda na sua máquina enquanto você escreve código e expõe tools com contexto de Angular pra um assistente de IA compatível, pelo [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro), o padrão aberto que a Anthropic lançou em [novembro de 2024](https://www.anthropic.com/news/model-context-protocol). O propósito é estreito e útil: o assistente ganha um caminho pra documentação atual do Angular, exemplos curados e o formato do seu workspace, e com isso para de gerar Angular do ano errado.

Antes do setup, duas observações, porque a sigla carrega coisas demais. Isto não é o WebMCP: o WebMCP é de runtime, onde o seu app publicado expõe tools tipadas pra um agente do browser, e eu separo os dois em [WebMCP vs Angular CLI MCP server](/angular/webmcp-vs-angular-cli-mcp-server/). E isto também não substitui o review: ele melhora o ponto de partida do assistente, mas não aprova o diff. O lado de review está em [Angular CLI MCP e código Angular gerado por IA](/angular/angular-cli-mcp-ai-generated-angular-code/). Este texto é o encanamento: como você sobe o servidor e conecta um client.

## Suba o servidor e aponte um client pra ele

Existem dois caminhos de entrada, e em geral você usa os dois. Rode `ng mcp` num terminal pra subir o servidor de forma interativa; a [doc](https://angular.dev/ai/mcp) diz que ele então imprime as instruções pra configurar um host. O formato que o seu editor de fato guarda é uma config de client que sobe o mesmo servidor via `npx`, e aí o client cuida do ciclo de vida do processo. A invocação canônica nessa config é `npx -y @angular/cli mcp`.

Um detalhe que pega o pessoal: o nome da chave muda por client. O VS Code espera um objeto `servers`; o Cursor, as IDEs da JetBrains, o Gemini CLI e a maioria dos outros esperam `mcpServers`. O mesmo comando, os mesmos args, uma chave de fora diferente. A config abaixo está no formato `mcpServers`, que a maioria dos clients lê.

*Suba o servidor, ou confira o CLI que o entrega*

```bash
# sobe de forma interativa (imprime as instruções de config do host)
ng mcp

# confirma a versão do CLI que traz o servidor
ng version
```

## O formato da config do client

Este é o bloco que um client guarda. Pro VS Code, troque a chave de fora de `mcpServers` pra `servers` e mantenha o resto. O `-y` no `npx` pula o prompt de instalação, então o client consegue subir o servidor sem precisar de você.

*mcp.json (clients com mcpServers: Cursor, JetBrains, Gemini CLI)*

```text
# mcp.json
# VS Code: renomeie a chave de fora de mcpServers pra servers
{
  "mcpServers": {
    "angular-cli": {
      "command": "npx",
      "args": ["-y", "@angular/cli", "mcp"]
    }
  }
}
```

## As tools que ele expõe

O servidor registra um conjunto padrão de tools de leitura e um segundo conjunto, atrás de uma flag, que consegue mexer no projeto. Essa separação importa pra política: as tools padrão respondem perguntas, as experimentais rodam builds e testes. Os nomes abaixo vêm direto da [página oficial](https://angular.dev/ai/mcp); não inventei nenhum. Trate a lista exata como sensível à versão e confira ela no seu próprio CLI, já que o servidor ainda é descrito como experimental.

Duas flags moldam a superfície sem você escolher tool por tool. O `--read-only` registra só as tools que não mudam o projeto (a doc faz a ressalva honesta de que o seu editor ainda pode editar por conta própria). O `--local-only` registra só as tools que funcionam offline. As tools experimentais entram por opção, via `--experimental-tool` (apelido `-E`); elas não vêm ligadas por padrão.

| Tool | Conjunto | O que faz |
|---|---|---|
| `search_documentation` | Padrão | Busca na documentação oficial do Angular. |
| `find_examples` | Padrão | Acha exemplos de código de uma base curada. |
| `get_best_practices` | Padrão | Traz o guia de boas práticas do Angular. |
| `list_projects` | Padrão | Lista os apps e libraries do workspace. |
| `onpush_zoneless_migration` | Padrão | Planeja uma migração OnPush ou zoneless passo a passo. |
| `ai_tutor` | Padrão | Sobe um tutor interativo de Angular (recomenda CLI v20+). |
| `build`, `test`, `e2e` | Experimental | Roda um build, os testes unitários ou os testes e2e. Atrás do `--experimental-tool`. |
| `modernize` | Experimental | Roda migrações de código e devolve as instruções de próximo passo. |
| `devserver.start` / `.stop` / `.wait_for_build` | Experimental | Controla um dev server e devolve os logs do build dele. |

## Conectando no seu client

Leia a linha que casa com o seu editor. O Claude Code recebe um comando de CLI e escreve a config do servidor pra você; o `--` separa as flags do próprio Claude do comando que ele deve rodar, e o `--scope project` guarda tudo num [.mcp.json](https://code.claude.com/docs/en/mcp) compartilhado na raiz do repo, em vez da sua config pessoal. O Cursor e o VS Code recebem um arquivo JSON direto, com aquela diferença de chave que mencionei acima.

| Client | Como você conecta | Onde fica |
|---|---|---|
| Claude Code | `claude mcp add angular-cli -- npx -y @angular/cli mcp` | Config pessoal por padrão; com `--scope project`, num `.mcp.json` compartilhado. |
| Cursor | Adicione o bloco `mcpServers` na config de MCP (do projeto ou global). | `.cursor/mcp.json` (projeto) ou a config global de MCP do Cursor. |
| VS Code (Copilot) | O mesmo bloco, mas a chave de fora é `servers`, não `mcpServers`. | `.vscode/mcp.json` ou o seu `settings.json` de usuário. |
| Outros clients de MCP | Use o bloco `mcpServers` com `npx -y @angular/cli mcp`. | O arquivo de config de MCP daquele client. |

*Claude Code: adicione o servidor e confirme que o CLI está presente*

```bash
# adiciona o Angular CLI MCP server (compartilhado com o time)
claude mcp add angular-cli --scope project -- npx -y @angular/cli mcp

# confere o CLI pelo qual o servidor roda
ng version
```

## Quando ele se paga em vez de um arquivo de regras simples

O servidor vale o esforço quando o seu assistente precisa de respostas vivas que um arquivo estático não dá: docs atuais de uma API cujo status você não tem certeza, a lista real de projetos de um workspace, ou um plano de migração gerado contra o seu código. Se a sua necessidade é só ensinar as convenções do time pro assistente, um arquivo de regras vai mais longe com menos máquina rodando, e o `ng generate ai-config` escreve um no formato que a sua ferramenta já lê. Eu uso os dois: o [AGENTS.md](/angular/agents-md-for-modern-angular/) pras regras fixas, o MCP server pras consultas vivas. Se eu tivesse que largar um num projeto pequeno, ficaria com o arquivo de regras, porque uma sugestão de API desatualizada sai mais barato de pegar no review do que uma convenção faltando sai de reexplicar em cada prompt.

## Artefato reaproveitável: Matriz de conexão do Angular CLI MCP

- Pra subir: `ng mcp` de forma interativa, ou deixe um client subir o `npx -y @angular/cli mcp`.
- Claude Code: `claude mcp add angular-cli -- npx -y @angular/cli mcp` (com `--scope project` pra um `.mcp.json` compartilhado).
- Cursor / Gemini CLI / JetBrains: um bloco `mcpServers` com `command: npx`, `args: [-y, @angular/cli, mcp]`.
- VS Code (Copilot): o mesmo bloco, mas a chave de fora é `servers`, não `mcpServers`.
- Pra limitar a superfície: `--read-only` pras tools que não mudam nada, `--local-only` pra offline, `--experimental-tool` pra ligar as tools de build/test.
- Confira a lista de tools no seu próprio CLI; o servidor ainda é descrito como experimental, então a lista pode mudar entre versões.

## Perguntas frequentes

### Qual comando sobe o Angular CLI MCP server?

Rode `ng mcp` num terminal pra subir de forma interativa; ele então imprime as instruções pra configurar um host. A maioria dos clients, em vez disso, guarda uma config que sobe o mesmo servidor via `npx -y @angular/cli mcp`, e aí o client gerencia o processo. Os dois caminhos estão na [página oficial](https://angular.dev/ai/mcp).

### Como adiciono no Claude Code?

Rode `claude mcp add angular-cli -- npx -y @angular/cli mcp`. O `--` separa as flags do próprio Claude Code do comando que ele roda. Adicione `--scope project` pra escrever um [.mcp.json](https://code.claude.com/docs/en/mcp) compartilhado na raiz do repo, em vez da sua config pessoal.

### Por que a minha config do VS Code não funciona com `mcpServers`?

O VS Code espera a chave de fora `servers`, enquanto o Cursor, as IDEs da JetBrains e o Gemini CLI esperam `mcpServers`. O `command` e os `args` são idênticos (`npx -y @angular/cli mcp`); só a chave de fora muda, conforme a [doc do Angular](https://angular.dev/ai/mcp).

### Quais tools ele expõe?

Seis tools padrão (`search_documentation`, `find_examples`, `get_best_practices`, `list_projects`, `onpush_zoneless_migration`, `ai_tutor`) e um grupo atrás do `--experimental-tool` (`build`, `test`, `e2e`, `modernize` e um grupo de devserver). A [página oficial](https://angular.dev/ai/mcp) é a fonte de verdade; trate a lista como sensível à versão.

## Fontes consultadas

- https://angular.dev/ai/mcp
- https://angular.dev/ai
- https://angular.dev/ai/develop-with-ai
- https://angular.dev/cli/generate/ai-config
- https://angular.dev/reference/releases
- https://code.claude.com/docs/en/mcp
- https://modelcontextprotocol.io/docs/getting-started/intro
- https://www.anthropic.com/news/model-context-protocol

## Leia também

- [Angular CLI MCP e código Angular gerado por IA](https://andreramos.dev/pt/angular/angular-cli-mcp-ai-generated-angular-code/)
- [WebMCP vs Angular CLI MCP server: tools em runtime vs ajuda em dev-time](https://andreramos.dev/pt/angular/webmcp-vs-angular-cli-mcp-server/)
- [Um AGENTS.md que faz a IA escrever Angular moderno](https://andreramos.dev/pt/angular/agents-md-for-modern-angular/)