Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mcp-use/mcp-use

mcp-use is the easiest way to interact with mcp servers with custom agents
https://github.com/mcp-use/mcp-use

agentic-framework ai apps-sdk chatgpt claude-code llms mcp mcp-apps mcp-client mcp-gateway mcp-host mcp-inspector mcp-server mcp-servers mcp-tools mcp-ui model-context-protocol modelcontextprotocol python typescript

Last synced: about 21 hours ago
JSON representation

mcp-use is the easiest way to interact with mcp servers with custom agents

Awesome Lists containing this project

README 

          


ย 



  

    

      

      

      mcp use logo

    

  



ย 



  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.




    

        

    

        

    

        

    

        

    

        

    

        

    


    

        Badge

    

        

    

        

    

        

    

        

    


    

        Badge

    

        

    

        

    

        

    

        

    

        

    


    

      

    

      






---



## 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 โ†“ |

        Python Docs |

        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



```bash

pip install mcp-use langchain-openai

```



```python

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**](./libraries/python/README.md#quick-start)



####  Typescript



```bash

npm install mcp-use @langchain/openai

```



```typescript

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**](./libraries/typescript/README.md#-quick-start)



---



### Use MCP Client



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



####  Python



```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**](./libraries/python/README.md#direct-tool-calls-without-llm)



####  Typescript



```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**](./libraries/typescript/README.md#basic-usage)



---



### Create an MCP Server



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



####  Typescript



```bash

npx create-mcp-use-app my-server

cd my-server

npm install

```



```typescript

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

import { z } from "zod";



const server = new MCPServer({

  name: "my-server",

  version: "1.0.0",

  description: "My custom MCP server",

});



// Define a tool

server.tool(

  {

    name: "get_weather",

    description: "Get weather for a city",

    schema: z.object({

      city: z.string().describe("City name"),

    }),

  },

  async ({ city }) => {

    return text(`Temperature: 72ยฐF, Condition: sunny, City: ${city}`);

  }

);



// Start server with auto-inspector

server.listen(3000);

// ๐ŸŽ‰ Inspector at http://localhost:3000/inspector

```



[**โ†’ Full TypeScript Server Documentation**](./libraries/typescript/README.md#%EF%B8%8F-mcp-server-framework)



####  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:



```typescript

server.listen(3000);

// Inspector automatically at: http://localhost:3000/inspector

```



#### Standalone



Inspect any MCP server via CLI:



```bash

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**](./libraries/typescript/packages/inspector/README.md)



---



## ๐Ÿ“š More Examples & Documentation



### Example Use Cases



- **[Web Browsing with Playwright](./libraries/python/README.md#web-browsing-with-playwright)** - Automate browser tasks

- **[Multi-Server Setup](./libraries/python/README.md#multi-server-support)** - Use multiple MCP servers together

- **[Streaming Responses](./libraries/python/README.md#streaming-agent-output)** - Real-time agent output

- **[UI Widgets](./libraries/typescript/README.md#building-custom-ui-widgets)** - Build interactive React components

- **[AI SDK Integration](./libraries/typescript/README.md#-ai-sdk-integration)** - Vercel AI SDK for Next.js apps



### Complete Documentation



- **[๐Ÿ“˜ Python Documentation](./libraries/python/README.md)** - Complete Python guide

- **[๐Ÿ“— TypeScript Documentation](./libraries/typescript/README.md)** - Complete TypeScript guide

- **[๐Ÿ” Inspector Documentation](./libraries/typescript/packages/inspector/README.md)** - Inspector guide

- **[๐ŸŒ Online Docs](https://mcp-use.com/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 | [![PyPI](https://img.shields.io/pypi/v/mcp_use.svg)](https://pypi.org/project/mcp_use/) |



### TypeScript Packages



| Package                | Description                                     | Version                                                                                                         |

| ---------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |

| **mcp-use**            | Core framework for clients, agents, and servers | [![npm](https://img.shields.io/npm/v/mcp-use.svg)](https://www.npmjs.com/package/mcp-use)                       |

| **@mcp-use/cli**       | Build tool with hot reload and auto-inspector   | [![npm](https://img.shields.io/npm/v/@mcp-use/cli.svg)](https://www.npmjs.com/package/@mcp-use/cli)             |

| **@mcp-use/inspector** | Web-based debugger for MCP servers              | [![npm](https://img.shields.io/npm/v/@mcp-use/inspector.svg)](https://www.npmjs.com/package/@mcp-use/inspector) |

| **create-mcp-use-app** | Project scaffolding tool                        | [![npm](https://img.shields.io/npm/v/create-mcp-use-app.svg)](https://www.npmjs.com/package/create-mcp-use-app) |



---



## ๐Ÿ—๏ธ 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](https://discord.gg/XkNkSkMz3V)

- **๐Ÿ› GitHub Issues**: [Report bugs or request features](https://github.com/mcp-use/mcp-use/issues)

- **๐Ÿ“– Documentation**: [mcp-use.com/docs](https://mcp-use.com/docs)

- **๐ŸŒ Website**: [mcp-use.com](https://mcp-use.com)

- **๐Ÿฆ Twitter**: Follow [@pietrozullo](https://x.com/pietrozullo) and [@pederzh](https://x.com/pederzh)



---



## ๐Ÿ“œ License



MIT ยฉ [MCP-Use Contributors](https://github.com/mcp-use/mcp-use/graphs/contributors)



---



## ๐Ÿ™ Contributing



We love contributions! Check out our contributing guidelines:



[CONTRIBUTING.md](https://github.com/mcp-use/mcp-use/blob/main/CONTRIBUTING.md)



---



## โญ Star History



[![Star History Chart](https://api.star-history.com/svg?repos=mcp-use/mcp-use&type=Date)](https://www.star-history.com/#mcp-use/mcp-use&Date)



---



## ๐Ÿ“ Citation



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



```bibtex

@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](https://github.com/pietrozullo))

2. **Luigi** ([@pederzh](https://github.com/pederzh))

3. **Enrico** ([@tonxxd](https://github.com/tonxxd))









  




---





  Built with โค๏ธ by the MCP-Use community

  


  San Francisco | Zรผrich