Mcp Use

Full-Stack MCP Framework

mcp-use provides everything you need to build with MCP servers, MCP clients and AI agents in 6 lines of code, in both Python and TypeScript.

---

Stack

• 🤖 MCP Agents - AI agents that can use tools and reason across steps
• 🔌 MCP Clients - Connect any LLM to any MCP server
• 🛠️ MCP Servers - Build your own MCP servers
• 🔍 MCP Inspector - Web-based debugger for MCP servers
• 🎨 MCP-UI Resources - Build ChatGPT apps with interactive widgets

---

🚀 What Do You Want to Build?

🤖 Build an AI Agent

Create intelligent agents that can use tools, browse the web, manage files, and more.

🔌 Use MCP Client

Connect directly to MCP servers and call tools programmatically without an agent.

🛠️ Create an MCP Server

Build your own MCP servers with tools, resources, and prompts.

🔍 Debug with Inspector

Test, debug, and explore your MCP servers interactively.

🎨 Build ChatGPT Apps

Create interactive UIs with mcp-ui, react and live reload.

☁️ Deploy to MCP Cloud

Deploy and manage your MCP agents and servers in the cloud.

---

📦 Quick Start

Build an AI Agent

Create an AI agent that can use MCP tools to accomplish complex tasks.

Python

pip install mcp-use langchain-openai

import asyncio
from langchain_openai import ChatOpenAI
from mcp_use import MCPAgent, MCPClient

async def main():
    # Configure MCP server
    config = {
        "mcpServers": {
            "filesystem": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
            }
        }
    }

    client = MCPClient.from_dict(config)
    llm = ChatOpenAI(model="gpt-4o")
    agent = MCPAgent(llm=llm, client=client)

    result = await agent.run("List all files in the directory")
    print(result)

asyncio.run(main())

**→ Full Python Agent Documentation**

Typescript

npm install mcp-use @langchain/openai

import { ChatOpenAI } from "@langchain/openai";
import { MCPAgent, MCPClient } from "mcp-use";

async function main() {
  // Configure MCP server
  const config = {
    mcpServers: {
      filesystem: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      },
    },
  };

  const client = MCPClient.fromDict(config);
  const llm = new ChatOpenAI({ modelName: "gpt-4o" });
  const agent = new MCPAgent({ llm, client });

  const result = await agent.run("List all files in the directory");
  console.log(result);
}

main();

**→ Full TypeScript Agent Documentation**

---

Use MCP Client

Connect to MCP servers directly without an AI agent for programmatic tool access.

Python

import asyncio
from mcp_use import MCPClient

async def main():
    config = {
        "mcpServers": {
            "calculator": {
                "command": "npx",
                "args": ["-y", "@modelcontextprotocol/server-everything"]
            }
        }
    }

    client = MCPClient.from_dict(config)
    await client.create_all_sessions()

    session = client.get_session("calculator")
    result = await session.call_tool(name="add", arguments={"a": 5, "b": 3})

    print(f"Result: {result.content[0].text}")
    await client.close_all_sessions()

asyncio.run(main())

**→ Python Client Documentation**

Typescript

import { MCPClient } from "mcp-use";

async function main() {
  const config = {
    mcpServers: {
      calculator: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-everything"],
      },
    },
  };

  const client = new MCPClient(config);
  await client.createAllSessions();

  const session = client.getSession("calculator");
  const result = await session.callTool("add", { a: 5, b: 3 });

  console.log(`Result: ${result.content[0].text}`);
  await client.closeAllSessions();
}

main();

**→ TypeScript Client Documentation**

---

Create an MCP Server

Build your own MCP server with custom tools, resources, and prompts.

Typescript

npx create-mcp-use-app my-server
cd my-server
npm install

import { createMCPServer } from "mcp-use/server";
import { z } from "zod";

const server = createMCPServer("my-server", {
  version: "1.0.0",
  description: "My custom MCP server",
});

// Define a tool
server.tool("get_weather", {
  description: "Get weather for a city",
  parameters: z.object({
    city: z.string().describe("City name"),
  }),
  execute: async ({ city }) => {
    return { temperature: 72, condition: "sunny", city };
  },
});

// Start server with auto-inspector
server.listen(3000);
// 🎉 Inspector at http://localhost:3000/inspector

**→ Full TypeScript Server Documentation**

Python

Coming Soon! For now, please use the TypeScript implementation to create MCP servers.

---

Use the Inspector

Debug and test your MCP servers with the interactive web-based inspector.

Automatic (with mcp-use server)

When you create a server with mcp-use, the inspector is automatically available:

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

Standalone

Inspect any MCP server via CLI:

npx @mcp-use/inspector --url http://localhost:3000/sse

Features:

• 🔍 Test tools interactively with live execution
• 📊 Monitor connection status and server health
• 🔐 Handle OAuth flows automatically
• 💾 Persistent sessions with localStorage

**→ Full Inspector Documentation**

---

📚 More Examples & Documentation

Example Use Cases

• **Web Browsing with Playwright** - Automate browser tasks
• **Multi-Server Setup** - Use multiple MCP servers together
• **Streaming Responses** - Real-time agent output
• **UI Widgets** - Build interactive React components
• **AI SDK Integration** - Vercel AI SDK for Next.js apps

Complete Documentation

• **📘 Python Documentation** - Complete Python guide
• **📗 TypeScript Documentation** - Complete TypeScript guide
• **🔍 Inspector Documentation** - Inspector guide
• **🌐 Online Docs** - Full online documentation

---

✨ Key Features

Feature

Description

Python

TypeScript

🤖 MCP Agents

AI agents with tool access and multi-step reasoning

✅

✅

🔌 MCP Clients

Direct connection to any MCP server

✅

✅

🛠️ MCP Servers

Build custom MCP servers

🔜

✅

🔍 Inspector

Web-based debugging tool

✅

✅

🎨 UI Widgets

Build interactive React UIs

➖

✅

🌐 Multi-Server

Connect to multiple servers simultaneously

✅

✅

📡 Streaming

Real-time streaming responses

✅

✅

📊 Observability

Built-in Langfuse integration

✅

✅

🔐 OAuth Support

Built-in OAuth flow handling

✅

✅

🛡️ Tool Control

Restrict access to specific tools

✅

✅

---

📦 Package Overview

This monorepo contains multiple packages for both Python and TypeScript:

Python Packages

Package	Description	Version
mcp-use	Complete MCP client and agent library

TypeScript Packages

Package	Description	Version
mcp-use	Core framework for clients, agents, and servers
@mcp-use/cli	Build tool with hot reload and auto-inspector
@mcp-use/inspector	Web-based debugger for MCP servers
create-mcp-use-app	Project scaffolding tool

---

🏗️ Repository Structure

mcp-use/
├── libraries/
│   ├── python/              → Python implementation
│   │   ├── mcp_use/         → Core library
│   │   ├── examples/        → Python examples
│   │   └── docs/            → Python documentation
│   │
│   └── typescript/          → TypeScript implementation
│       └── packages/
│           ├── mcp-use/     → Core framework
│           ├── cli/         → Build tool
│           ├── inspector/   → Web inspector
│           └── create-mcp-use-app/  → Scaffolding
└── README.md               → This file

---

🌟 Why MCP-Use?

Complete Vertical Stack

Build everything from AI agents to servers - not just clients. Create the full MCP ecosystem in your preferred language.

Language Flexibility

Choose Python for ML/data workflows or TypeScript for web applications. Same great features, different languages.

Production Ready

Includes observability, streaming, multi-server support, sandboxing, and tool access controls out of the box.

Developer Experience

Hot reload, TypeScript/Python type safety, built-in inspector, and comprehensive documentation.

Open Source

MIT licensed and community-driven. Contribute, fork, or extend as needed.

---

🤝 Community & Support

• 💬 Discord: Join our community
• 🐛 GitHub Issues: Report bugs or request features
• 📖 Documentation: docs.mcp-use.com
• 🌐 Website: mcp-use.com
• 🐦 Twitter: Follow @pietrozullo and @pederzh

---

📜 License

MIT © MCP-Use Contributors

---

🙏 Contributing

We love contributions! Check out our contributing guidelines:

• Python Contributing Guide
• TypeScript Contributing Guide

---

⭐ Star History

---

📝 Citation

If you use MCP-Use in your research or project, please cite:

@software{mcp_use2025,
  author = {Zullo, Pietro and Contributors},
  title = {MCP-Use: Complete MCP Ecosystem for Python and TypeScript},
  year = {2025},
  publisher = {GitHub},
  url = {https://github.com/mcp-use/mcp-use}
}

---

Contributors

Thanks to all our amazing contributors!

Core Contributors

1. Pietro (@pietrozullo)

2. Luigi (@pederzh)

3. Enrico (@tonxxd)

---