UNPKG

mcp-use

Version:

A utility library for integrating Model Context Protocol (MCP) with LangChain, Zod, and related tools. Provides helpers for schema conversion, event streaming, and SDK usage.

213 lines (163 loc) • 7.14 kB
<div align="center" style="margin: 0 auto; max-width: 80%;"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./static/logo_white.svg"> <source media="(prefers-color-scheme: light)" srcset="./static/logo_black.svg"> <img alt="mcp use logo" src="./static/logo_white.svg" width="80%" style="margin: 20px auto;"> </picture> </div> <h1 align="center">Unified MCP Client Library</h1> <p align="center"> <a href="https://www.npmjs.com/package/mcp-use" alt="NPM Downloads"> <img src="https://img.shields.io/npm/dw/mcp-use.svg"/></a> <a href="https://www.npmjs.com/package/mcp-use" alt="NPM Version"> <img src="https://img.shields.io/npm/v/mcp-use.svg"/></a> <a href="https://docs.mcp-use.io" alt="Documentation"> <img src="https://img.shields.io/badge/docs-mcp--use.io-blue" /></a> <a href="https://mcp-use.io" alt="Website"> <img src="https://img.shields.io/badge/website-mcp--use.io-blue" /></a> <a href="https://github.com/mcp-use/mcp-use-ts/blob/main/LICENSE" alt="License"> <img src="https://img.shields.io/github/license/mcp-use/mcp-use-ts" /></a> <a href="https://eslint.org" alt="Code style: ESLint"> <img src="https://img.shields.io/badge/code%20style-eslint-4B32C3.svg" /></a> <a href="https://github.com/mcp-use/mcp-use-ts/stargazers" alt="GitHub stars"> <img src="https://img.shields.io/github/stars/mcp-use/mcp-use-ts?style=social" /></a> <a href="https://discord.gg/XkNkSkMz3V" alt="Discord"> <img src="https://dcbadge.limes.pink/api/server/XkNkSkMz3V?style=flat" /></a> </p> 🌐 **MCP Client** is the open-source way to connect **any LLM to any MCP server** in TypeScript/Node.js, letting you build custom agents with tool access without closed-source dependencies. šŸ’” Let developers easily connect any LLM via LangChain.js to tools like web browsing, file operations, 3D modeling, and more. --- ## ✨ Key Features | Feature | Description | | ------------------------------- | -------------------------------------------------------------------------- | | šŸ”„ **Ease of use** | Create an MCP-capable agent in just a few lines of TypeScript. | | šŸ¤– **LLM Flexibility** | Works with any LangChain.js-supported LLM that supports tool calling. | | 🌐 **HTTP Support** | Direct SSE/HTTP connection to MCP servers. | | āš™ļø **Dynamic Server Selection** | Agents select the right MCP server from a pool on the fly. | | 🧩 **Multi-Server Support** | Use multiple MCP servers in one agent. | | šŸ›”ļø **Tool Restrictions** | Restrict unsafe tools like filesystem or network. | | šŸ”§ **Custom Agents** | Build your own agents with LangChain.js adapter or implement new adapters. | --- ## šŸš€ Quick Start ### Requirements - Node.js 22.0.0 or higher - npm, yarn, or pnpm (examples use pnpm) ### Installation ```bash # Install from npm npm install mcp-use # LangChain.js and your LLM provider (e.g., OpenAI) npm install langchain @langchain/openai dotenv ``` Create a `.env`: ```ini OPENAI_API_KEY=your_api_key ``` ### Basic Usage ```ts import { ChatOpenAI } from '@langchain/openai' import { MCPAgent, MCPClient } from 'mcp-use' import 'dotenv/config' async function main() { // 1. Configure MCP servers const config = { mcpServers: { playwright: { command: 'npx', args: ['@playwright/mcp@latest'] } } } const client = MCPClient.fromDict(config) // 2. Create LLM const llm = new ChatOpenAI({ modelName: 'gpt-4o' }) // 3. Instantiate agent const agent = new MCPAgent({ llm, client, maxSteps: 20 }) // 4. Run query const result = await agent.run('Find the best restaurant in Tokyo using Google Search') console.log('Result:', result) } main().catch(console.error) ``` --- ## šŸ“‚ Configuration File You can store servers in a JSON file: ```json { "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } } ``` Load it: ```ts import { MCPClient } from 'mcp-use' const client = MCPClient.fromConfigFile('./mcp-config.json') ``` --- ## šŸ“š Examples We provide a comprehensive set of examples demonstrating various use cases. All examples are located in the `examples/` directory with a dedicated README. ### Running Examples ```bash # Install dependencies npm install # Run any example npm run example:airbnb # Search accommodations with Airbnb npm run example:browser # Browser automation with Playwright npm run example:chat # Interactive chat with memory npm run example:filesystem # File system operations npm run example:http # HTTP server connection npm run example:everything # Test MCP functionalities npm run example:multi # Multiple servers in one session ``` ### Example Highlights - **Browser Automation**: Control browsers to navigate websites and extract information - **File Operations**: Read, write, and manipulate files through MCP - **Multi-Server**: Combine multiple MCP servers (Airbnb + Browser) in a single task - **Sandboxed Execution**: Run MCP servers in isolated E2B containers - **OAuth Flows**: Authenticate with services like Linear using OAuth2 See the [examples README](./examples/README.md) for detailed documentation and prerequisites. --- ## šŸ”„ Multi-Server Example ```ts const config = { mcpServers: { airbnb: { command: 'npx', args: ['@openbnb/mcp-server-airbnb'] }, playwright: { command: 'npx', args: ['@playwright/mcp@latest'] } } } const client = MCPClient.fromDict(config) const agent = new MCPAgent({ llm, client, useServerManager: true }) await agent.run('Search Airbnb in Barcelona, then Google restaurants nearby') ``` --- ## šŸ”’ Tool Access Control ```ts const agent = new MCPAgent({ llm, client, disallowedTools: ['file_system', 'network'] }) ``` ## šŸ‘„ Contributors <table> <tr> <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0"> <a href=https://github.com/zandko> <img src=https://avatars.githubusercontent.com/u/37948383?v=4 width="100;" style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Zane/> <br /> <sub style="font-size:14px"><b>Zane</b></sub> </a> </td> <td align="center" style="word-wrap: break-word; width: 150.0; height: 150.0"> <a href=https://github.com/pietrozullo> <img src=https://avatars.githubusercontent.com/u/62951181?v=4 width="100;" style="border-radius:50%;align-items:center;justify-content:center;overflow:hidden;padding-top:10px" alt=Pietro Zullo/> <br /> <sub style="font-size:14px"><b>Pietro Zullo</b></sub> </a> </td> </tr> </table> <!-- Contributors section will be automatically generated here --> ## šŸ“œ License MIT Ā© [Zane](https://github.com/zandko)