Installation

Choose Your Language

mcp-use is available in both TypeScript and Python with consistent APIs across both languages.

TypeScript
Python

TypeScript Installation

Prerequisites

Node.js Version: Node.js 20.19.0 or higher (22+ recommended)

Check your Node.js version:

node --version

If you need to upgrade, visit nodejs.org or use a version manager like nvm.

Package Managers

npm install mcp-use

pnpm add mcp-use

yarn add mcp-use

bun add mcp-use

Core Dependencies

mcp-use requires Zod for schema validation:

npm install mcp-use zod

Optional Dependencies

Depending on your use case, you may want to install additional packages:

For Building Agents

npm install mcp-use @langchain/openai langchain
# or for Anthropic
npm install mcp-use @langchain/anthropic langchain

For React Widgets

npm install mcp-use react react-dom

For Observability

npm install mcp-use langfuse langfuse-langchain

For AI SDK Integration

npm install mcp-use ai @langchain/anthropic

For Code Mode (E2B)

npm install mcp-use @e2b/code-interpreter

Development Tools

For the best development experience, also install:

# CLI tool with hot reload and inspector
npm install -D @mcp-use/cli

# TypeScript and build tools
npm install -D typescript tsx @types/node

Project Scaffolding

The fastest way to start a new project:

npx create-mcp-use-app my-project

This creates a fully configured project with:

TypeScript configuration
Example server with tools and widgets
Hot reload setup
Auto-opening inspector
Build and deployment scripts

Verify Installation

Create a test file test.ts:

import { MCPServer, text } from "mcp-use/server";
import { z } from "zod";

const server = new MCPServer({
  name: "test-server",
  version: "1.0.0",
});

server.tool({
  name: "hello",
  description: "Say hello",
  schema: z.object({}),
}, async () => text("Hello from mcp-use!"));

await server.listen(3000);
console.log("Server running at http://localhost:3000");

Run it:

npx tsx test.ts

You should see:

Server running at http://localhost:3000
🔍 Inspector: http://localhost:3000/inspector
🚀 MCP endpoint: http://localhost:3000/mcp

Python Installation

Prerequisites

Python Version: Python 3.11 or higher is required

Check your Python version:

python --version
# or
python3 --version

If you need to upgrade, visit python.org.

Install with pip

pip install mcp-use

git clone https://github.com/mcp-use/mcp-use.git
cd mcp-use/libraries/python
pip install -e .

Virtual Environment (Recommended)

Always use a virtual environment for Python projects:

# Create virtual environment
python -m venv env

# Activate on Linux/Mac
source env/bin/activate

# Activate on Windows
env\Scripts\activate

# Install mcp-use
pip install mcp-use

LangChain Providers

mcp-use works with various LLM providers through LangChain. Install the provider you need:

pip install mcp-use langchain-openai

pip install mcp-use langchain-anthropic

pip install mcp-use langchain-groq

pip install mcp-use langchain-google-genai

Only models with tool calling capabilities can be used. Ensure your chosen model supports function calling.

Optional Dependencies

For Search Capabilities

pip install mcp-use[search]
# Includes fastembed for semantic search

For E2B Sandboxed Execution

pip install mcp-use[e2b]
# Includes e2b-code-interpreter

For Development

pip install mcp-use[dev]
# Includes pytest, black, ruff, mypy, and more

All Optional Dependencies

pip install mcp-use[dev,search,e2b,anthropic,openai]

Environment Variables

Create a .env file for your API keys:

# OpenAI
OPENAI_API_KEY=your_openai_key

# Anthropic
ANTHROPIC_API_KEY=your_anthropic_key

# E2B (for sandboxed execution)
E2B_API_KEY=your_e2b_key

# Langfuse (for observability)
LANGFUSE_PUBLIC_KEY=your_public_key
LANGFUSE_SECRET_KEY=your_secret_key
LANGFUSE_HOST=https://cloud.langfuse.com

Load them in your code:

from dotenv import load_dotenv
load_dotenv()

Verify Installation

Create a test file test.py:

import asyncio
from mcp_use import MCPClient

async def main():
    config = {
        "mcpServers": {
            "everything": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-everything"],
            }
        }
    }
    
    client = MCPClient.from_dict(config)
    await client.create_all_sessions()
    
    session = client.get_session("everything")
    result = await session.call_tool(
        name="add",
        arguments={"a": 5, "b": 3}
    )
    
    print(f"Result: {result.content[0].text}")
    await client.close_all_sessions()

if __name__ == "__main__":
    asyncio.run(main())

Run it:

python test.py

You should see:

Result: 8

Development Setup

For contributing or development:

# Clone the repository
git clone https://github.com/mcp-use/mcp-use.git
cd mcp-use/libraries/python

# Create virtual environment
python -m venv env
source env/bin/activate  # or env\Scripts\activate on Windows

# Install in development mode with all dependencies
pip install -e ".[dev,anthropic,openai,search,e2b]"

# Run tests
pytest

# Run linting
ruff check --fix
ruff format

IDE Setup

Visual Studio Code

Recommended extensions: TypeScript:

ESLint
Prettier
TypeScript and JavaScript Language Features

Python:

Python (Microsoft)
Pylance
Ruff

TypeScript Configuration

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Troubleshooting

TypeScript: Module not found

Make sure you’re importing from the correct subpaths:

import { MCPServer } from "mcp-use/server";  // ✅ Correct
import { MCPAgent } from "mcp-use/agent";    // ✅ Correct
import { MCPClient } from "mcp-use/client";  // ✅ Correct
import { useWidget } from "mcp-use/react";   // ✅ Correct

Python: Import errors

Make sure your virtual environment is activated and mcp-use is installed:

# Check if mcp-use is installed
pip list | grep mcp-use

# Reinstall if needed
pip install --upgrade mcp-use

Node version issues

mcp-use requires Node.js 20.19.0 or higher. Use nvm to switch versions:

nvm install 22
nvm use 22

Python version issues

mcp-use requires Python 3.11+. Check your version:

python --version

Use pyenv to manage Python versions:

pyenv install 3.11
pyenv local 3.11

Getting Started

Core Concepts

Guides

Choose Your Language

TypeScript Installation

Prerequisites

Package Managers

Core Dependencies

Optional Dependencies

Development Tools

Project Scaffolding

Verify Installation

Python Installation

Prerequisites

Install with pip

Virtual Environment (Recommended)

LangChain Providers

Optional Dependencies

Environment Variables

Verify Installation

Development Setup

IDE Setup

Visual Studio Code

TypeScript Configuration

Troubleshooting

Next Steps

Quickstart

Concepts

​Choose Your Language

​TypeScript Installation

​Prerequisites

​Package Managers

​Core Dependencies

​Optional Dependencies

​Development Tools

​Project Scaffolding

​Verify Installation

​Python Installation

​Prerequisites

​Install with pip

​Virtual Environment (Recommended)

​LangChain Providers

​Optional Dependencies

​Environment Variables

​Verify Installation

​Development Setup

​IDE Setup

​Visual Studio Code

​TypeScript Configuration

​Troubleshooting

​Next Steps

Quickstart

Concepts

Choose Your Language

TypeScript Installation

Prerequisites

Package Managers

Core Dependencies

Optional Dependencies

Development Tools

Project Scaffolding

Verify Installation

Python Installation

Prerequisites

Install with pip

Virtual Environment (Recommended)

LangChain Providers

Optional Dependencies

Environment Variables

Verify Installation

Development Setup

IDE Setup

Visual Studio Code

TypeScript Configuration

Troubleshooting

Next Steps