mcp-use

---

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. Quick Start ↓ | Python Docs | TypeScript Docs	🔌 Use MCP Client Connect directly to MCP servers and call tools programmatically without an agent. Quick Start ↓ | Python Docs | TypeScript Docs
🛠️ Create an MCP Server Build your own MCP servers with tools, resources, and prompts. Quick Start ↓ | TypeScript Docs	🔍 Debug with Inspector Test, debug, and explore your MCP servers interactively. Quick Start ↓ | Inspector Docs | MCP Inspector online
🎨 Build ChatGPT Apps Create interactive UIs with mcp-ui, react and live reload. Quick Start | Templates	☁️ Deploy to MCP Cloud Deploy and manage your MCP agents and servers in the cloud. Quick Start | 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)

---