Full-Stack MCP Framework

mcp-use provides everything you need to build with Model Context Protocol
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?

📦 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

📦 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)