mcp-client

library0.0.0jsnpmunverified

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.

llm-agents http-networking

npm install mcp-client

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MCP-CLIENT

mcp-client

llm-agentsjavascriptv0.0.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.

MCPClient

✓ import { MCPClient } from 'mcp-client';

✗ const { MCPClient } = require('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

✓ import type { MCPClientEvents } from 'mcp-client';

✗ import { MCPClientEvents } from 'mcp-client';

Use `import type` for type-only imports to prevent bundling issues and ensure correct TypeScript compilation.

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();

Debug

Known issues

deprecatedThe `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`.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

Errors

Common errors & fixes

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.

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.

MCP client encountered an error: ConnectTimeoutError: Connect timeout

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: Command not found: <command_name>

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.

Upgrade

Version history

0.0.0latest on npm

Audit

Dependencies

zodoptionalRequired for defining custom result schemas when calling tools.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/punkpeye/mcp-client ↗

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

homepagehttps://glama.ai/mcp ↗