nx-mcp

library0.24.0jsnpmunverified

The `nx-mcp` package, currently at version `0.24.0`, implements a server for the Model Context Protocol (MCP) specifically for Nx monorepos. This server provides Large Language Models (LLMs) with deep, structured access to an Nx workspace's internal architecture, encompassing project relationships, file mappings, runnable tasks, ownership information, tech stacks, and Nx generators. This capability allows AI agents to generate code with precise context, understand the downstream impact of changes, and apply modifications accurately across interconnected files within a monorepo. Although it functions as a standalone CLI server, its development and releases are closely tied to the Nx Console VS Code extension, which often automatically manages its lifecycle. Its key differentiator is leveraging Nx's inherent understanding of monorepo structure to offer a richer, more actionable context for AI compared to generic code embeddings.

devops llm-agents

npm install nx-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NX-MCP

nx-mcp

devopsjavascriptv0.24.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

nx-mcp command invocation (stdio)

✓ npx nx-mcp@latest

✗ nx-mcp (if not globally installed); npm install -g nx-mcp && nx-mcp (less common for transient use)

This package is primarily a CLI server, not a programmatic library. AI clients integrate by configuring its command-line execution, typically for `stdio` communication as shown in `mcp.json` configurations.

nx-mcp command invocation (HTTP SSE)

✓ npx nx-mcp@latest --sse --port 3000

✗ npx nx-mcp@latest --port 3000 (missing --sse)

For concurrent connections or non-stdio communication, the server supports HTTP SSE mode. This requires explicit `--sse` and `--port` flags in the command arguments.

nx-mcp minimal mode disabling

✓ npx nx-mcp@latest --no-minimal

✗ Assuming all tools are available by default.

By default, `nx-mcp` runs in 'minimal mode,' which hides certain workspace analysis tools like `nx_workspace` or `nx_generators` to reduce AI context clutter. Explicitly add the `--no-minimal` flag if your AI agent requires access to the full suite of tools.

This quickstart demonstrates how to configure the `nx-mcp` server for AI clients using `mcp.json` for both `stdio` and `http` transport, and how to invoke it directly via `npx`.

{ "servers": { "nx-mcp-stdio": { "type": "stdio", "command": "npx", "args": ["nx-mcp@latest"] }, "nx-mcp-http": { "type": "http", "command": "npx", "args": ["nx-mcp@latest", "--sse", "--port", "3000"] } } } # Then, run directly via npx: npx nx-mcp@latest --help # Or, for HTTP mode: npx nx-mcp@latest --sse --port 3000

nx-mcp --version

Debug

Known issues

gotchaThe `nx-mcp` server defaults to 'minimal mode', which explicitly hides several tools like `nx_workspace`, `nx_project_details`, and `nx_generators` to reduce AI context window usage. If your AI agent relies on these tools, you must disable minimal mode.

fix

Invoke `nx-mcp` with the `--no-minimal` flag: `npx nx-mcp@latest --no-minimal`.

affects: >=0.24.0

gotchaFor configuring specific options or behaviors of the `nx-mcp` server, such as polygraph tools or other experimental features, a dedicated configuration file is used.

fix

Create a `.nx/nx-mcp-config.json` file in your workspace root to pass additional options to the server. Refer to `nx-mcp --help` for available configurations.

affects: >=0.24.0

gotchaBy default, `nx-mcp` communicates via `stdio` (standard input/output), which is suitable for single-client interactions. For scenarios requiring multiple concurrent connections or external client integration, an HTTP transport layer is available.

fix

Start the server with the `--sse` and `--port` flags to enable HTTP SSE (Server-Sent Events) communication: `npx nx-mcp@latest --sse --port <desired_port>`.

affects: >=0.24.0

gotchaSome tools within `nx-mcp`, particularly those related to 'polygraph' functionality, may be experimental or subject to casing changes and rapid evolution.

fix

Always refer to the latest documentation or `nx-mcp --help` for the most current tool names and usage. Be prepared for minor adjustments in how experimental tools are invoked or how their outputs are structured.

affects: >=0.24.0

Errors

Common errors & fixes

AI Agent error: Tool 'nx_workspace' not found or not available.

The `nx-mcp` server is running in its default 'minimal mode', which hides certain tools.

fix

Restart the `nx-mcp` server with the `--no-minimal` flag: `npx nx-mcp@latest --no-minimal`.

Failed to connect to MCP server at given address/port.

The AI client is misconfigured regarding the `nx-mcp` server's communication method (stdio vs. HTTP) or address/port.

fix

Ensure that if your AI client expects HTTP communication, `nx-mcp` is launched with `--sse --port <your_port>`, and the client is configured to connect to that port. For `stdio`, ensure the client correctly spawns and connects to the process's standard streams.

Command 'nx-mcp' not found.

`nx-mcp` is not globally installed or `npx` (or equivalent package runner) is not being used to invoke it.

fix

Use `npx nx-mcp@latest` to run the package without global installation, or ensure it's listed as a dependency and run via `pnpm exec nx-mcp`, `yarn nx-mcp`, or `npm exec nx-mcp`.

Upgrade

Version history

0.24.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Amazon

Resources

githubhttps://github.com/nrwl/nx-console ↗

packagehttps://www.npmjs.com/package/nx-mcp ↗

homepagehttps://nx.dev ↗