🎯 What is MCP-Use?

📦 Packages Overview

🚀 Quick Start

# Create a new MCP applicationnpx create-mcp-use-app my-mcp-app# Navigate to your projectcd my-mcp-app# Start development with hot reload and auto-inspectornpm run dev

📚 Package Documentation

mcp-use: Core Framework

As an MCP Client

import{MCPClient,MCPAgent}from'mcp-use'import{ChatOpenAI}from'@langchain/openai'// Configure MCP serversconstclient=MCPClient.fromDict({mcpServers:{filesystem:{command:'npx',args:['@modelcontextprotocol/server-filesystem']},github:{command:'npx',args:['@modelcontextprotocol/server-github'],env:{GITHUB_TOKEN:process.env.GITHUB_TOKEN}}}})// Create an AI agentconstagent=newMCPAgent({llm:newChatOpenAI({model:'gpt-4'}),  client,maxSteps:10})// Use the agent with natural languageconstresult=awaitagent.run('Search for TypeScript files in the project and create a summary')

As an MCP Server Framework

import{createMCPServer}from'mcp-use/server'import{z}from'zod'// Create your MCP serverconstserver=createMCPServer('weather-server',{version:'1.0.0',description:'Weather information MCP server'})// Define tools with Zod schemasserver.tool('get_weather',{description:'Get current weather for a city',parameters:z.object({city:z.string().describe('City name'),units:z.enum(['celsius','fahrenheit']).optional()}),execute:async({ city, units='celsius'})=>{constweather=awaitfetchWeather(city,units)return{temperature:weather.temp,condition:weather.condition,humidity:weather.humidity}}})// Define resourcesserver.resource('weather_map',{description:'Interactive weather map',uri:'weather://map',mimeType:'text/html',fetch:async()=>{returngenerateWeatherMapHTML()}})// Start the serverserver.listen(3000)// 🎉 Inspector automatically available at http://localhost:3000/inspector// 🚀 MCP endpoint at http://localhost:3000/mcp

Advanced Features

import{streamEventsToAISDKWithTools}from'mcp-use'import{LangChainAdapter}from'ai'// In your Next.js API routeexportasyncfunctionPOST(req:Request){const{ prompt}=awaitreq.json()conststreamEvents=agent.streamEvents(prompt)constenhancedStream=streamEventsToAISDKWithTools(streamEvents)constreadableStream=createReadableStreamFromGenerator(enhancedStream)returnLangChainAdapter.toDataStreamResponse(readableStream)}

// resources/analytics-dashboard.tsximport{useMcp}from'mcp-use/react'exportdefaultfunctionAnalyticsDashboard(){const{ callTool, status}=useMcp()const[data,setData]=useState(null)useEffect(()=>{callTool('get_analytics',{period:'7d'}).then(setData)},[])return(<div><h1>Analytics Dashboard</h1>{/* Your dashboard UI */}</div>)}

@mcp-use/cli

# Development with hot reloadmcp-use dev# Production buildmcp-use build# Start production servermcp-use start

# Start developmentmcp-use dev# Server running at http://localhost:3000# Inspector opened at http://localhost:3000/inspector# Watching for changes...# Make changes to your code# Server automatically restarts# UI widgets hot reload# Inspector updates in real-time

@mcp-use/inspector

server.listen(3000)// Inspector at http://localhost:3000/inspector

npx mcp-inspect --url https://mcp.example.com/sse

import{mountInspector}from'@mcp-use/inspector'mountInspector(app,'/debug')

create-mcp-use-app

# Interactive modenpx create-mcp-use-app# Direct modenpx create-mcp-use-app my-app --template advanced

💡 Real-World Examples

Example 1: AI-Powered File Manager

// Create an agent that can manage filesconstagent=newMCPAgent({llm:newChatOpenAI(),client:MCPClient.fromDict({mcpServers:{filesystem:{command:'npx',args:['@modelcontextprotocol/server-filesystem','/Users/me/documents']}}})})// Natural language file operationsawaitagent.run('Organize all PDF files into a "PDFs" folder sorted by date')awaitagent.run('Find all TypeScript files and create a project summary')awaitagent.run('Delete all temporary files older than 30 days')

Example 2: Multi-Tool Research Assistant

// Connect multiple MCP serversconstclient=MCPClient.fromDict({mcpServers:{browser:{command:'npx',args:['@playwright/mcp']},search:{command:'npx',args:['@mcp/server-search']},memory:{command:'npx',args:['@mcp/server-memory']}}})constresearcher=newMCPAgent({llm:newChatAnthropic(),  client,useServerManager:true// Auto-select appropriate server})// Complex research taskconstreport=awaitresearcher.run(`  Research the latest developments in quantum computing.  Search for recent papers, visit official websites,  and create a comprehensive summary with sources.`)

Example 3: Database Admin Assistant

constserver=createMCPServer('db-admin',{version:'1.0.0'})server.tool('execute_query',{description:'Execute SQL query safely',parameters:z.object({query:z.string(),database:z.string()}),execute:async({ query, database})=>{// Validate and execute queryconstresults=awaitdb.query(query,{ database})return{rows:results,count:results.length}}})// Create an AI-powered DBAconstdba=newMCPAgent({llm:newChatOpenAI({model:'gpt-4'}),client:newMCPClient({url:'http://localhost:3000/mcp'})})awaitdba.run('Show me all users who signed up this week')awaitdba.run('Optimize the slow queries in the performance log')

🏗️ Project Structure

my-mcp-app/├── src/│   └── index.ts          # MCP server definition├── resources/            # UI widgets (React components)│   ├── dashboard.tsx     # Main dashboard widget│   └── settings.tsx      # Settings panel widget├── package.json         # Dependencies and scripts├── tsconfig.json        # TypeScript configuration├── .env                 # Environment variables└── dist/               # Build output    ├── index.js        # Compiled server    └── resources/      # Compiled widgets

🛠️ Development Workflow

Local Development

# 1. Create your projectnpx create-mcp-use-app my-project# 2. Start developmentcd my-projectnpm run dev# 3. Make changes - hot reload handles the rest# 4. Test with the auto-opened inspector

Production Deployment

# Build for productionnpm run build# Deploy with Dockerdocker build -t my-mcp-server.docker run -p 3000:3000 my-mcp-server# Or deploy to any Node.js hostnpm run start

🤝 Community & Support

📊 Publishing & Version Management

Using Changesets (Recommended)

# Create a changeset for your changespnpm changeset# Version packages based on changesetspnpm changeset version# Publish all changed packagespnpm changeset publish

Manual Publishing

# Publish individual packagespnpm --filter mcp-use publish --access publicpnpm --filter @mcp-use/cli publish --access publicpnpm --filter @mcp-use/inspector publish --access publicpnpm --filter create-mcp-use-app publish --access public# Or publish all at oncepnpm -r publish --access public

🧑‍💻 Contributing

Development Setup

# Clone the repositorygit clone https://github.com/mcp-use/mcp-use-ts.gitcd mcp-use-ts# Install dependenciespnpm install# Build all packagespnpm build# Run testspnpmtest# Start developmentpnpm dev

📜 License