Full-Stack MCP Framework

MCP-Use provides everything you need to build with the Model Context Protocol
from AI agents to servers, in both Python and TypeScript.

• 🤖 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

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

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

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

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

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

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

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

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

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

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

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

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

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

• 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

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

This monorepo contains multiple packages for both Python and TypeScript:

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

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

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

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

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

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

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

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

• 💬 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

MIT © MCP-Use Contributors

We love contributions! Check out our contributing guidelines:

• Python Contributing Guide
• TypeScript Contributing Guide

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}
}

Thanks to all our amazing contributors!

1. Pietro (@pietrozullo)
2. Luigi (@pederzh)
3. Enrico (@tonxxd)