NX
OfficialAI & MLProductivity

Nx MCP Server: Codebase Architecture for LLMs

Enable LLMs to access Nx codebase architecture via the MCP server, revealing project relationships and runnable tasks to power precise AI code suggestions.

View on GitHub
Quick Install
npx -y @apps/nx-mcp

Overview

The Nx MCP Server is a lightweight Model Context Protocol (MCP) server that lets large language models (LLMs) and editor integrations query an Nx workspace’s architecture and runnable tasks. By exposing up-to-date project graphs, target/task definitions, and generator schemas, the MCP server gives AI assistants precise, workspace-aware context so they can produce accurate code suggestions, generate project-scoped changes, and recommend which tests or builds to run.

You can run the MCP server from the Nx Console extension or install and run it standalone inside a repository. It’s designed to sit next to your workspace, serve a machine-readable view of projects and relationships, and keep that information current as the workspace changes — enabling more reliable and reproducible AI-driven workflows.

Features

  • Exposes workspace metadata that LLMs need:
    • Project graph and dependency relationships
    • Runnable targets/tasks and their configurations
    • Generator schemas (available generators and their options)
    • Relevant file snippets or config fragments for context
  • Designed for integration with editors and AI assistants (e.g., VS Code, Cursor)
  • Can run bundled with Nx Console or standalone as an NPM package
  • Keeps context up-to-date by reading the workspace configuration (nx.json, project.json, workspace.json, package.json)
  • Lightweight HTTP/WebSocket-based API (Model Context Protocol) to serve context to clients
  • Simple configuration: choose host/port, workspace root, and optional access controls

Installation / Configuration

You have three common ways to run the MCP server: via the Nx Console extension (automatic), from source in the monorepo, or as a standalone NPM package. Example commands below assume common package managers — replace with your preferred tooling.

Run from an Nx workspace (development)

# Using pnpm (preferred in many Nx repos)
pnpm nx serve nx-mcp

# Using npm scripts if your workspace offers an Nx wrapper
npm run nx -- serve nx-mcp

# Or with the nx CLI directly
nx serve nx-mcp

Install and run the standalone package

# Install as a development dependency
npm install --save-dev nx-mcp
# or
pnpm add -D nx-mcp

# Run via npx (if package exposes a CLI)
npx nx-mcp start --workspace .

# Alternatively, add an npm script (package.json)
"scripts": {
  "start:mcp": "nx-mcp start --workspace ."
}

Environment / configuration examples

# Common environment variables (examples)
export MCP_HOST=127.0.0.1
export MCP_PORT=3333
export MCP_WORKSPACE=/path/to/your/repo   # optional, defaults to current working dir
export MCP_AUTH_TOKEN=secret-token        # optional access control

VS Code / extension settings example

// settings.json
{
  "nxConsole.mcpUrl": "http://localhost:3333",
  "nxConsole.mcpAuthToken": "secret-token"
}

Note: exact CLI flags and environment variable names depend on the packaged CLI shipped with the server. Check the installed package’s README or the source in apps/nx-mcp for exact option names.

Available Resources

The MCP server typically exposes (via HTTP/WS) structured endpoints that provide the following resources to clients:

  • Project graph: nodes (projects), edges (dependencies), implicit/explicit relationships
  • Task/target catalog: available targets for each project (build/test/lint/serve), default options, and executor info
  • Generator registry: available schematics/generators, their JSON schemas, default values, and prompts
  • File snippets/config extracts: relevant lines from workspace config files to give LLMs precise context
  • Change impact info: which projects are affected by a set of file changes (useful for targeted testing or CI)

Clients integrate by fetching these JSON resources and feeding them to the LLM as context, or by subscribing to updates via WebSocket for near real-time synchronization.

Use Cases

  1. Context-aware code completion and patch generation

    • An LLM can request a project’s package of targets and generator schemas before generating a code change, producing patches that respect workspace boundaries and existing build targets.

  2. Intelligent PR suggestions and scoped refactors

    • Before proposing a refactor, the assistant queries the project graph and affected projects. It can then run only the relevant tests and include a precise changelog of affected modules.

  3. Guided generator workflows

    • An AI-driven UI asks the MCP server for generator schemas (options, types, defaults). It presents a validated UI and produces the exact CLI command to run the generator with the chosen flags.

  4. Prioritized CI and test runs

    • A CI assistant computes the minimal set of projects that need to run based on a file diff pulled through MCP, reducing unnecessary work and speeding up feedback loops.

  5. Workspace documentation and navigation

    • Editors can show a Project Details View with the latest targets and configuration snippets surfaced by the MCP server — helpful when onboarding new contributors.

Troubleshooting and Tips

  • If the MCP server appears stale, restart it or ensure it watches workspace config files so it can recompute the project graph.
  • Use an access token (if supported) when exposing the server across a network or when multiple users share a development machine.
  • Combine MCP-provided context with short, specific LLM prompts to avoid hallucination and get actionable suggestions.
  • Keep the server local or on a trusted network; it exposes workspace structure and snippets that may be sensitive.
  • Source (monorepo app): apps/nx-mcp in the Nx Console repository
    • https://github.com/nrwl/nx-console/tree/master/apps/nx-mcp
Tags:ai-mlproductivity