mcp-ts

An easier client SDK for MCP

A thin wrapper around the official MCP SDK that just works everywhere - Node, Bun, Deno, and browsers without configuration headaches.

This is a client-only version of the MCP TypeScript SDK that provides tools for interacting with MCP servers.

Why this exists?

The official SDK has some funny quirks that make it difficult to use:

• No more import failures due to missing .js extensions
• No verbose subpath-only exports
• Works seamlessly with Bun, Deno, and bundlers like Vite/Webpack
• LLMs (Claude, GPT) can generate valid code without special documentation

Same functionality as the official SDK, just packaged to eliminate common developer frustrations.

Installation

npm install mcp-ts

That's it! All dependencies are automatically included - you don't need to install the Model Context Protocol SDK separately.

For detailed installation instructions for different project types (TypeScript, ESM, CommonJS), see INSTALL.md.

Usage

TypeScript (recommended)

import { MCPClient, MCPToolSpec } from "mcp-ts";

// Define your own return type for strong typing
interface CalculationResult {
  value: number;
  unit: string;
}

async function main() {
  // Create a client
  const client = await MCPClient.create("https://your-mcp-server.com/endpoint");

  // List available tools with proper typing
  const tools: MCPToolSpec[] = await client.listTools();

  // Call a tool with typed response
  const result = await client.callTool<CalculationResult>("calculator", {
    a: 5,
    b: 10,
    operation: "add",
  });

  // TypeScript knows the shape of the result
  console.log(`Result: ${result.value} ${result.unit}`);
}

// Properly handle the promise
main().catch((error) => console.error("Unhandled error:", error));

ESM (JavaScript)

import { MCPClient } from "mcp-ts";

// Create a client
const client = await MCPClient.create("https://your-mcp-server.com/endpoint");

// List available tools
const tools = await client.listTools();
console.log(tools);

// Call a tool
const result = await client.callTool("toolName", { param1: "value1" });
console.log(result);

CommonJS

const { MCPClient } = require("mcp-ts");

// Create a client
const client = await MCPClient.create("https://your-mcp-server.com/endpoint");

// Use client as with ESM

Testing

You can verify that the package and its dependencies are working correctly by running:

# Test both ESM and CommonJS imports
npm run test:full

# Test only ESM imports
npm run test:imports:esm

# Test only CommonJS imports
npm run test:imports:cjs

# Test TypeScript imports
npm run test:imports:ts

This will build the package and run test scripts that try to import and use the client.

If you're experiencing import issues, make sure:

• You're using the correct import syntax for your environment (see Usage section above)

• Your package.json has the correct configuration:

  {
    "type": "module" // For ESM projects
    // or remove this line for CommonJS projects
  }
  

TypeScript Integration

This package includes TypeScript type definitions and can be used in TypeScript projects without additional configuration. The main exports are:

• MCPClient: The main client class
• MCPToolSpec: Interface describing the structure of tools returned by listTools()

You can use generic type parameters with the callTool method to specify the expected response type:

interface MyResponse {
  status: string;
  data: number[];
}

const result = await client.callTool<MyResponse>("myTool", { param: "value" });
// result is typed as MyResponse

API Reference

MCPClient

The main client class for interacting with MCP servers.

Static Methods

• static async create(endpoint: string): Promise<MCPClient> - Creates a client using SSE transport
• static async createWithHTTP(endpoint: string): Promise<MCPClient> - Creates a client using HTTP transport

Instance Methods

• async listTools(): Promise<MCPToolSpec[]> - Lists all available tools from the server
• async callTool<T>(name: string, args: Record<string, unknown>): Promise<T> - Calls a tool with arguments

License

MIT