@purinton/mcp-client

@purinton/mcp-client

A robust Node.js client for connecting to Model Context Protocol (MCP) servers with automatic reconnect, authentication, and flexible transport support.

Table of Contents

• Features
• Installation
• Usage
  • ESM Example
  • CommonJS Example
• API
• TypeScript
• License

Features

• Connects to MCP servers with automatic reconnect
• Supports both ESM and CommonJS
• Customizable log, transport, and client classes
• Reads configuration from environment variables or options
• TypeScript type definitions included

Installation

npm install @purinton/mcp-client

Usage

ESM Example

import mcpClient from '@purinton/mcp-client';

(async () => {
  try {
    const client = await mcpClient({
      // token: 'your-mcp-token',
      // baseUrl: 'http://localhost:1234/',
    });
    console.log('MCP Client connected:', !!client);
    // Use the client as needed...
  } catch (err) {
    console.error('Failed to connect MCP Client:', err);
  }
})();

CommonJS Example

const mcpClient = require('@purinton/mcp-client');

(async () => {
  try {
    const client = await mcpClient({
      // token: 'your-mcp-token',
      // baseUrl: 'http://localhost:1234/',
    });
    console.log('MCP Client connected:', !!client);
    // Use the client as needed...
  } catch (err) {
    console.error('Failed to connect MCP Client:', err);
  }
})();

API

mcpClient(options?: McpClientOptions): Promise<any>

Creates and connects an MCP client. Returns a connected client instance. Automatically reconnects on disconnect.

Options (McpClientOptions)

• log (optional): Custom log (default: @purinton/log)
• port (optional): MCP server port (default: 1234)
• baseUrl (optional): MCP server URL (default: http://localhost:1234/)
• token (optional): Authentication token (default: from MCP_TOKEN env)
• ClientClass (optional): Custom client class (default: SDK Client)
• TransportClass (optional): Custom transport class (default: SDK StreamableHTTPClientTransport)

TypeScript

Type definitions are included:

import mcpClient, { McpClientOptions } from '@purinton/mcp-client';

const client = await mcpClient({
  token: 'your-mcp-token',
  baseUrl: 'http://localhost:1234/',
} as McpClientOptions);

Support

For help, questions, or to chat with the author and community, visit:

Purinton Dev on Discord

License

MIT © 2025 Russell Purinton

Links

• GitHub
• npm
• Discord