---
title: "The Angular CLI MCP Server: Setup, Tools, and Wiring It to Your AI Assistant"
description: "How to set up the Angular CLI MCP server: the exact start command, the client config shape, the tools it exposes, and how to wire it to Claude Code, Cursor, and VS Code."
deck: "The Angular CLI ships a dev-time MCP server that hands Angular-aware tools to your AI assistant. You start it with `ng mcp`, or point a client at `npx -y @angular/cli mcp`. The [official page](https://angular.dev/ai/mcp) still calls it experimental and exposes six standard tools plus a set behind `--experimental-tool`, on a CLI that recommends v20 or later."
author: "André Ramos"
url: "https://andreramos.dev/angular/angular-mcp-server-setup/"
lang: "en"
type: "article"
---

# The Angular CLI MCP Server: Setup, Tools, and Wiring It to Your AI Assistant

> The Angular CLI ships a dev-time MCP server that hands Angular-aware tools to your AI assistant. You start it with `ng mcp`, or point a client at `npx -y @angular/cli mcp`. The [official page](https://angular.dev/ai/mcp) still calls it experimental and exposes six standard tools plus a set behind `--experimental-tool`, on a CLI that recommends v20 or later.

## What the server actually is

The Angular CLI MCP server is a dev-time process. It runs on your machine while you write code and exposes Angular-aware tools to a compatible AI assistant over the [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro), the open standard Anthropic released in [November 2024](https://www.anthropic.com/news/model-context-protocol). The point is narrow and useful: the assistant gets a path to current Angular documentation, curated examples, and your workspace layout, so it stops generating Angular from the wrong year.

Two clarifications before the setup, because the acronym is overloaded. This is not WebMCP: WebMCP is runtime, where your shipped app exposes typed tools to a browser agent, and I keep the two apart in [WebMCP vs the Angular CLI MCP server](/angular/webmcp-vs-angular-cli-mcp-server/). And this is not a substitute for review: it improves the assistant's starting point, it does not approve the diff. The review side lives in [Angular CLI MCP and AI-Generated Angular Code](/angular/angular-cli-mcp-ai-generated-angular-code/). This piece is the plumbing: how you start the server and connect a client.

## Start it, then point a client at it

There are two ways in, and you usually use both. Run `ng mcp` in a terminal to start the server interactively; the [docs](https://angular.dev/ai/mcp) note it then prints instructions for configuring a host. The form your editor actually persists is a client config that launches the same server through `npx`, so the client owns the process lifecycle. The canonical invocation in that config is `npx -y @angular/cli mcp`.

One detail that bites people: the key name differs by client. VS Code expects a `servers` object; Cursor, JetBrains IDEs, the Gemini CLI, and most others expect `mcpServers`. Same command, same args, different wrapper key. The config below is the `mcpServers` shape most clients read.

*Start the server, or check the CLI that ships it*

```bash
# start it interactively (prints host config instructions)
ng mcp

# confirm the CLI version that ships the server
ng version
```

## The client config shape

This is the block a client persists. For VS Code, change the outer key from `mcpServers` to `servers` and keep everything else. The `-y` on `npx` skips the install prompt so the client can launch the server unattended.

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

```text
# mcp.json
# VS Code: rename the outer key from mcpServers to servers
{
  "mcpServers": {
    "angular-cli": {
      "command": "npx",
      "args": ["-y", "@angular/cli", "mcp"]
    }
  }
}
```

## The tools it exposes

The server registers a default set of read-style tools and a second set, behind a flag, that can touch your project. The split matters for policy: the default tools answer questions, the experimental ones run builds and tests. The names below come straight from the [official page](https://angular.dev/ai/mcp); I am not inventing any. Treat the exact roster as version-sensitive and check it against your own CLI, since the server is still described as experimental.

Two flags shape the surface area without you hand-picking tools. `--read-only` registers only tools that do not change the project (the docs add the honest caveat that your editor may still perform edits on its own). `--local-only` registers only tools that work offline. The experimental tools are opt-in through `--experimental-tool` (alias `-E`); they are not on by default.

| Tool | Set | What it does |
|---|---|---|
| `search_documentation` | Standard | Searches the official Angular documentation. |
| `find_examples` | Standard | Finds code examples from a curated database. |
| `get_best_practices` | Standard | Retrieves the Angular best practices guide. |
| `list_projects` | Standard | Lists the apps and libraries in the workspace. |
| `onpush_zoneless_migration` | Standard | Plans an OnPush or zoneless migration step by step. |
| `ai_tutor` | Standard | Launches an interactive Angular tutor (CLI v20+ recommended). |
| `build`, `test`, `e2e` | Experimental | Run a build, the unit tests, or the e2e tests. Behind `--experimental-tool`. |
| `modernize` | Experimental | Runs code migrations and returns next-step instructions. |
| `devserver.start` / `.stop` / `.wait_for_build` | Experimental | Controls a dev server and returns its build logs. |

## Wiring it to your client

Read the row that matches your editor. Claude Code takes a CLI command and writes the server into config for you; the `--` separates Claude's own flags from the command it should run, and `--scope project` persists it to a shared [.mcp.json](https://code.claude.com/docs/en/mcp) at the repo root instead of your personal config. Cursor and VS Code take a JSON file directly, with the wrapper-key difference noted above.

| Client | How you connect it | Where it lands |
|---|---|---|
| Claude Code | `claude mcp add angular-cli -- npx -y @angular/cli mcp` | Personal config by default; add `--scope project` for a shared `.mcp.json`. |
| Cursor | Add the `mcpServers` block to the MCP config (project or global). | `.cursor/mcp.json` (project) or the global Cursor MCP config. |
| VS Code (Copilot) | Same block, but the outer key is `servers`, not `mcpServers`. | `.vscode/mcp.json` or your user `settings.json`. |
| Other MCP clients | Use the `mcpServers` block with `npx -y @angular/cli mcp`. | That client's MCP config file. |

*Claude Code: add the server, then verify the CLI is present*

```bash
# add the Angular CLI MCP server (shared with the team)
claude mcp add angular-cli --scope project -- npx -y @angular/cli mcp

# sanity-check the CLI the server runs through
ng version
```

## When it earns its place over a plain rules file

The server is worth wiring up when your assistant needs live answers it cannot get from a static file: current docs for an API whose status you are unsure of, the real list of projects in a workspace, or a migration plan generated against your code. If your need is simply teaching the assistant your conventions, a rules file goes further with less moving machinery, and `ng generate ai-config` writes one in the format your tool already reads. I run both: the [AGENTS.md](/angular/agents-md-for-modern-angular/) file for standing rules, the MCP server for live lookups. If I had to drop one on a small project, I would keep the rules file, because a stale API suggestion is cheaper to catch in review than a missing convention is to re-explain on every prompt.

## Reusable artifact: Angular CLI MCP connection matrix

- Start it: `ng mcp` interactively, or let a client launch `npx -y @angular/cli mcp`.
- Claude Code: `claude mcp add angular-cli -- npx -y @angular/cli mcp` (add `--scope project` for a shared `.mcp.json`).
- Cursor / Gemini CLI / JetBrains: an `mcpServers` block with `command: npx`, `args: [-y, @angular/cli, mcp]`.
- VS Code (Copilot): the same block, but the outer key is `servers`, not `mcpServers`.
- Limit the surface: `--read-only` for non-mutating tools, `--local-only` for offline, `--experimental-tool` to opt into build/test tools.
- Verify the tool list against your own CLI; the server is still described as experimental, so the roster can move between versions.

## FAQ

### What command starts the Angular CLI MCP server?

Run `ng mcp` from a terminal to start it interactively; it then prints instructions for configuring a host. Most clients instead persist a config that launches the same server through `npx -y @angular/cli mcp`, so the client manages the process. Both routes are documented on the [official page](https://angular.dev/ai/mcp).

### How do I add it to Claude Code?

Run `claude mcp add angular-cli -- npx -y @angular/cli mcp`. The `--` separates Claude Code's own flags from the command it runs. Add `--scope project` to write a shared [.mcp.json](https://code.claude.com/docs/en/mcp) at the repo root instead of your personal config.

### Why does my VS Code config not work with `mcpServers`?

VS Code expects the outer key `servers`, while Cursor, JetBrains IDEs, and the Gemini CLI expect `mcpServers`. The `command` and `args` are identical (`npx -y @angular/cli mcp`); only the wrapper key changes, per the [Angular docs](https://angular.dev/ai/mcp).

### Which tools does it expose?

Six standard tools (`search_documentation`, `find_examples`, `get_best_practices`, `list_projects`, `onpush_zoneless_migration`, `ai_tutor`) and a set behind `--experimental-tool` (`build`, `test`, `e2e`, `modernize`, and a devserver group). The [official page](https://angular.dev/ai/mcp) is the source of truth; treat the roster as version-sensitive.

## Sources checked

- 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

## Related

- [Angular CLI MCP and AI-Generated Angular Code](https://andreramos.dev/angular/angular-cli-mcp-ai-generated-angular-code/)
- [WebMCP vs the Angular CLI MCP Server: Runtime Tools vs Dev-Time Help](https://andreramos.dev/angular/webmcp-vs-angular-cli-mcp-server/)
- [An AGENTS.md That Makes AI Write Modern Angular](https://andreramos.dev/angular/agents-md-for-modern-angular/)