MCP Client for Node.js

1.13.1 verified Sat Apr 25 auth: no javascript

mcp-client is a Node.js client library designed for simplified interaction with servers implementing the Model Context Protocol (MCP). As of version 1.13.1, this library offers a more convenient and less verbose API compared to the official MCP TypeScript SDK, abstracting lower-level details such as pagination and direct Zod schema handling. It distinguishes itself by employing more conventional method names (e.g., `getTools` instead of `listTools`). The client supports `httpStream` (recommended) and `stdio` connection types, with Server-Sent Events (SSE) connections explicitly marked as deprecated. It provides comprehensive functionalities for tool discovery and invocation, resource management (reading, listing), prompt interaction (getting, listing, completing), and receiving logging messages from the MCP server. While a specific release cadence is not detailed, the version history and recent publish date indicate active development.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module <path>/pkce-challenge/dist/index.node.js from <path>/@modelcontextprotocol/sdk/dist/cjs/client/auth.js not supported. ↓

cause Attempting to `require()` an ESM-only module within a CommonJS context, typically from an underlying dependency of `mcp-client`.

fix

Configure your project to use ES Modules by adding "type": "module" to your package.json, or use dynamic import() for the conflicting package if possible, though this may require modifications to @modelcontextprotocol/sdk's internal handling.

error MCP client encountered an error: ConnectTimeoutError: Connect timeout ↓

cause The client could not establish a connection to the specified MCP server within the timeout period.

fix

Verify that the url in client.connect() is correct and that the MCP server is running and accessible at that address and port. Check firewall rules or network configuration if connecting to a remote server.

error Error: Command not found: <command_name> ↓

cause When using `type: "stdio"` connection, the `command` specified for launching the MCP server subprocess is not found in the system's PATH.

fix

Ensure the command is correctly spelled and is either in your system's PATH or provide an absolute path to the executable in the command option.

Warnings

deprecated The `type: "sse"` connection method is deprecated. The underlying Model Context Protocol has shifted from SSE to Streamable HTTP as the preferred transport mechanism. ↓

fix Migrate to `type: "httpStream"` for new client connections. Existing SSE implementations may still function due to backward compatibility in the protocol, but new development should use `httpStream`.

gotcha The underlying `@modelcontextprotocol/sdk` (which `mcp-client` relies on) can cause `Error [ERR_REQUIRE_ESM]` when used in CommonJS projects, particularly due to dependencies like `pkce-challenge` being ESM-only. ↓

fix Ensure your project is configured for ESM by setting `"type": "module"` in your `package.json`. If using CommonJS is unavoidable, consider dynamic `import()` or transpilation setups (e.g., Webpack/Babel) to handle ESM-only dependencies.

Install

npm install mcp-client

yarn add mcp-client

pnpm add mcp-client

Imports

MCPClient
wrong
```
const { MCPClient } = require('mcp-client');
```
correct
```
import { MCPClient } from 'mcp-client';
```
The library primarily uses named ESM imports. While CJS might work via transpilation or specific Node.js settings, direct `require()` is not the idiomatic or recommended way due to potential underlying ESM dependencies.
MCPClientEvents
wrong
```
import { MCPClientEvents } from 'mcp-client';
```
correct
```
import type { MCPClientEvents } from 'mcp-client';
```
Use `import type` for type-only imports to prevent bundling issues and ensure correct TypeScript compilation.

Quickstart

Initializes an MCP client, connects via httpStream, pings the server, lists tools, and calls a basic tool.

import { MCPClient } from 'mcp-client';
import { z } from 'zod'; // Only needed if you use custom schemas

async function runClient() {
  const client = new MCPClient({
    name: "MyAwesomeMCPClient",
    version: "1.0.0",
  });

  try {
    // Connect using the recommended Streamable HTTP transport
    await client.connect({
      type: "httpStream",
      url: process.env.MCP_SERVER_URL ?? "http://localhost:8080/mcp",
    });
    console.log('Connected to MCP server.');

    // Ping the server to check connectivity
    await client.ping();
    console.log('Server responded to ping.');

    // List all available tools
    const tools = await client.getAllTools();
    console.log('Available tools:', tools.map(t => t.name));

    // Example: Call a simple 'add' tool
    const addResult = await client.callTool({
      name: 'add',
      arguments: { a: 5, b: 3 }
    });
    console.log('Result of add(5, 3):', addResult);

  } catch (error) {
    console.error('MCP client encountered an error:', error);
  } finally {
    // Clean up if necessary (e.g., disconnect stdio processes)
    // For httpStream, connection is typically stateless.
  }
}

runClient();