mirror of
https://github.com/mcp-use/mcp-use.git
synced 2026-09-14 18:06:01 +08:00
docs: update README files for Python and TypeScript implementations
- Renamed Python README title to "MCP-Use for Python" and added a description of its capabilities. - Enhanced Python README with sections on MCP Agent, MCP Client, and upcoming MCP Server. - Updated TypeScript README to include a new section on MCP-UI Resources for building interactive applications. - Improved formatting and added quick links in both README files for better navigation. - Ensured consistency in package descriptions and features across both implementations.
This commit is contained in:
Enrico Toniato
@@ -0,0 +1,557 @@
|
||||
<div align="center">
|
||||
<div align="center" style="margin: 0 auto; max-width: 80%;">
|
||||
<a href="https://mcp-use.com">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="./static/logo_white.svg">
|
||||
<source media="(prefers-color-scheme: light)" srcset="./static/logo_black.svg">
|
||||
<img alt="mcp use logo" src="./static/logo_black.svg" width="80%" style="margin: 20px auto;">
|
||||
</picture>
|
||||
</a>
|
||||
</div>
|
||||
|
||||
<h1 align="center" style="border:0; font-style:italic; font-weight:300;">Full-Stack MCP Framework</h1>
|
||||
<p align="center" style="max-width:600px; margin-bottom:40px">
|
||||
<b>MCP-Use</b> provides everything you need to build with the <a href="https://modelcontextprotocol.io">Model Context Protocol</a> <br/> from AI agents to servers, in both <b>Python</b> and <b>TypeScript</b>.</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/mcp-use/mcp-use/stargazers" alt="GitHub stars">
|
||||
<img src="https://img.shields.io/github/stars/mcp-use/mcp-use?style=social" /></a>
|
||||
<a href="https://pypi.org/project/mcp_use/" alt="PyPI Downloads">
|
||||
<img src="https://static.pepy.tech/badge/mcp-use" /></a>
|
||||
<a href="https://pypi.org/project/mcp_use/" alt="PyPI Version">
|
||||
<img src="https://img.shields.io/pypi/v/mcp_use.svg"/></a>
|
||||
<a href="https://www.npmjs.com/package/mcp-use" alt="NPM Downloads">
|
||||
<img src="https://img.shields.io/npm/dw/mcp-use.svg"/></a>
|
||||
<a href="https://www.npmjs.com/package/mcp-use" alt="NPM Version">
|
||||
<img src="https://img.shields.io/npm/v/mcp-use.svg"/></a>
|
||||
<a href="https://github.com/mcp-use/mcp-use/blob/main/LICENSE" alt="License">
|
||||
<img src="https://img.shields.io/github/license/mcp-use/mcp-use" /></a>
|
||||
<a href="https://docs.mcp-use.com" alt="Documentation">
|
||||
<img src="https://img.shields.io/badge/docs-mcp--use.com-blue" /></a>
|
||||
<a href="https://discord.gg/XkNkSkMz3V" alt="Discord">
|
||||
<img src="https://dcbadge.limes.pink/api/server/XkNkSkMz3V?style=flat" /></a>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
### 🏗️ 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
|
||||
|
||||
---
|
||||
|
||||
<h2 align="left" style="border:0; margin-top:50px">🚀 What Do You Want to Build?</h2>
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="50%" valign="top">
|
||||
<h3>🤖 Build an AI Agent</h3>
|
||||
<p>Create intelligent agents that can use tools, browse the web, manage files, and more.</p>
|
||||
<p>
|
||||
<a href="#build-an-ai-agent">Quick Start ↓</a> |
|
||||
<a href="./libraries/python/README.md#quick-start">Python Docs</a> |
|
||||
<a href="./libraries/typescript/README.md#-quick-start">TypeScript Docs</a>
|
||||
</p>
|
||||
</td>
|
||||
<td width="50%" valign="top">
|
||||
<h3>🔌 Use MCP Client</h3>
|
||||
<p>Connect directly to MCP servers and call tools programmatically without an agent.</p>
|
||||
<p>
|
||||
<a href="#use-mcp-client">Quick Start ↓</a> |
|
||||
<a href="./libraries/python/README.md#direct-tool-calls-without-llm">Python Docs</a> |
|
||||
<a href="./libraries/typescript/README.md#basic-usage">TypeScript Docs</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%" valign="top">
|
||||
<h3>🛠️ Create an MCP Server</h3>
|
||||
<p>Build your own MCP servers with tools, resources, and prompts.</p>
|
||||
<p>
|
||||
<a href="#create-an-mcp-server">Quick Start ↓</a> |
|
||||
<a href="./libraries/typescript/README.md#%EF%B8%8F-mcp-server-framework">TypeScript Docs</a>
|
||||
</p>
|
||||
</td>
|
||||
<td width="50%" valign="top">
|
||||
<h3>🔍 Debug with Inspector</h3>
|
||||
<p>Test, debug, and explore your MCP servers interactively.</p>
|
||||
<p>
|
||||
<a href="#use-the-inspector">Quick Start ↓</a> |
|
||||
<a href="./libraries/typescript/packages/inspector/README.md">Inspector Docs</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td width="50%" valign="top">
|
||||
<h3>🎨 Build ChatGPT Apps Apps</h3>
|
||||
<p>Create interactive UIs with mcp-ui, react and live reload.</p>
|
||||
<p>
|
||||
<a href="./libraries/typescript/README.md#mcp-ui-resources">Quick Start</a> |
|
||||
<a href="./libraries/typescript/packages/create-mcp-use-app/README.md">Templates</a>
|
||||
</p>
|
||||
</td>
|
||||
<td width="50%" valign="top">
|
||||
<h3>☁️ Deploy to MCP Cloud</h3>
|
||||
<p>Deploy and manage your MCP agents and servers in the cloud.</p>
|
||||
<p>
|
||||
<a href="./libraries/typescript/README.md#mcp-ui-resources">Quick Start</a> |
|
||||
<a href="./libraries/typescript/packages/create-mcp-use-app/README.md">Cloud ↗</a>
|
||||
</p>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
---
|
||||
|
||||
<h2 style="border:0; margin-top:30px;">📦 Quick Start</h2>
|
||||
|
||||
### 🤖 Build an AI Agent
|
||||
|
||||
Create an AI agent that can use MCP tools to accomplish complex tasks.
|
||||
|
||||
#### <img src="./static/python.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> 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)
|
||||
|
||||
#### <img src="./static/typescript.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> 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.
|
||||
|
||||
#### <img src="./static/python.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> 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)
|
||||
|
||||
#### <img src="./static/typescript.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> 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.
|
||||
|
||||
#### <img src="./static/typescript.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> Typescript
|
||||
|
||||
```bash
|
||||
npx create-mcp-use-app my-server
|
||||
cd my-server
|
||||
npm install
|
||||
```
|
||||
|
||||
```typescript
|
||||
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**](./libraries/typescript/README.md#%EF%B8%8F-mcp-server-framework)
|
||||
|
||||
#### <img src="./static/python.svg" height="14" style="margin-right:4px; top:-1px; position:relative;" align="center" /> 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://docs.mcp-use.com)** - Full online documentation
|
||||
|
||||
---
|
||||
|
||||
## ✨ Key Features
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th width="200">Feature</th>
|
||||
<th>Description</th>
|
||||
<th>Python</th>
|
||||
<th>TypeScript</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>🤖 MCP Agents</strong></td>
|
||||
<td>AI agents with tool access and multi-step reasoning</td>
|
||||
<td align="center">✅</td>
|
||||
<td align="center">✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>🔌 MCP Clients</strong></td>
|
||||
<td>Direct connection to any MCP server</td>
|
||||
<td align="center">✅</td>
|
||||
<td align="center">✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>🛠️ MCP Servers</strong></td>
|
||||
<td>Build custom MCP servers</td>
|
||||
<td align="center">🔜</td>
|
||||
<td align="center">✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>🔍 Inspector</strong></td>
|
||||
<td>Web-based debugging tool</td>
|
||||
<td align="center">✅</td>
|
||||
<td align="center">✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>🎨 UI Widgets</strong></td>
|
||||
<td>Build interactive React UIs</td>
|
||||
<td align="center">➖</td>
|
||||
<td align="center">✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>🌐 Multi-Server</strong></td>
|
||||
<td>Connect to multiple servers simultaneously</td>
|
||||
<td align="center">✅</td>
|
||||
<td align="center">✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>📡 Streaming</strong></td>
|
||||
<td>Real-time streaming responses</td>
|
||||
<td align="center">✅</td>
|
||||
<td align="center">✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>📊 Observability</strong></td>
|
||||
<td>Built-in Langfuse integration</td>
|
||||
<td align="center">✅</td>
|
||||
<td align="center">✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>🔐 OAuth Support</strong></td>
|
||||
<td>Built-in OAuth flow handling</td>
|
||||
<td align="center">✅</td>
|
||||
<td align="center">✅</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>🛡️ Tool Control</strong></td>
|
||||
<td>Restrict access to specific tools</td>
|
||||
<td align="center">✅</td>
|
||||
<td align="center">✅</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
---
|
||||
|
||||
## 📦 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 | [](https://pypi.org/project/mcp_use/) |
|
||||
|
||||
### TypeScript Packages
|
||||
|
||||
| Package | Description | Version |
|
||||
| ---------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
||||
| **mcp-use** | Core framework for clients, agents, and servers | [](https://www.npmjs.com/package/mcp-use) |
|
||||
| **@mcp-use/cli** | Build tool with hot reload and auto-inspector | [](https://www.npmjs.com/package/@mcp-use/cli) |
|
||||
| **@mcp-use/inspector** | Web-based debugger for MCP servers | [](https://www.npmjs.com/package/@mcp-use/inspector) |
|
||||
| **create-mcp-use-app** | Project scaffolding tool | [](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**: [docs.mcp-use.com](https://docs.mcp-use.com)
|
||||
- **🌐 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:
|
||||
|
||||
- [Python Contributing Guide](./libraries/python/CONTRIBUTING.md)
|
||||
- [TypeScript Contributing Guide](./libraries/typescript/README.md#-contributing)
|
||||
|
||||
---
|
||||
|
||||
## ⭐ Star History
|
||||
|
||||
[](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))
|
||||
|
||||
<br>
|
||||
|
||||
<a href="https://github.com/mcp-use/mcp-use/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=mcp-use/mcp-use" />
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
<strong>Built with ❤️ by the MCP-Use community</strong>
|
||||
<br/>
|
||||
<sub>Python • TypeScript • MCP Protocol</sub>
|
||||
</div>
|
||||
+55
-30
@@ -7,8 +7,7 @@
|
||||
</picture>
|
||||
</div>
|
||||
|
||||
|
||||
<h1 align="center">🚀 Create MCP Clients and Agents</h1>
|
||||
<h1 align="center">🚀 MCP-Use for Python</h1>
|
||||
<p align="center">
|
||||
<a href="https://github.com/pietrozullo/mcp-use/stargazers" alt="GitHub stars">
|
||||
<img src="https://img.shields.io/github/stars/pietrozullo/mcp-use?style=social" /></a>
|
||||
@@ -16,37 +15,42 @@
|
||||
<img src="https://static.pepy.tech/badge/mcp-use" /></a>
|
||||
<a href="https://pypi.org/project/mcp_use/" alt="PyPI Version">
|
||||
<img src="https://img.shields.io/pypi/v/mcp_use.svg"/></a>
|
||||
<a href="https://github.com/mcp-use/mcp-use-ts" alt="TypeScript">
|
||||
<img src="https://img.shields.io/badge/TypeScript-mcp--use-3178C6?logo=typescript&logoColor=white" /></a>
|
||||
<a href="https://github.com/pietrozullo/mcp-use/blob/main/LICENSE" alt="License">
|
||||
<img src="https://img.shields.io/github/license/pietrozullo/mcp-use" /></a>
|
||||
<a href="https://docs.mcp-use.com" alt="Documentation">
|
||||
<img src="https://img.shields.io/badge/docs-mcp--use.com-blue" /></a>
|
||||
<a href="https://mcp-use.com" alt="Website">
|
||||
<img src="https://img.shields.io/badge/website-mcp--use.com-blue" /></a>
|
||||
</p>
|
||||
<p align="center">
|
||||
<a href="https://x.com/pietrozullo" alt="Twitter Follow - Pietro">
|
||||
<img src="https://img.shields.io/twitter/follow/Pietro?style=social" /></a>
|
||||
<a href="https://x.com/pederzh" alt="Twitter Follow - Luigi">
|
||||
<img src="https://img.shields.io/twitter/follow/Luigi?style=social" /></a>
|
||||
<a href="https://discord.gg/XkNkSkMz3V" alt="Discord">
|
||||
<img src="https://dcbadge.limes.pink/api/server/XkNkSkMz3V?style=flat" /></a>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
🌐 MCP-Use is the open source way to connect **any LLM to any MCP server** and build custom MCP agents that have tool access, without using closed source or application clients.
|
||||
> **📦 Part of the [MCP-Use Monorepo](../../README.md)** - This is the Python implementation. Also available in [TypeScript](../typescript/README.md).
|
||||
|
||||
💡 Let developers easily connect any LLM to tools like web browsing, file operations, and more.
|
||||
🌐 **MCP-Use for Python** is the complete way to connect **any LLM to any MCP server** and build custom MCP agents with tool access.
|
||||
|
||||
- If you want to get started quickly check out [mcp-use.com website](https://mcp-use.com/) to build and deploy agents with your favorite MCP servers.
|
||||
- Visit the [mcp-use docs](https://docs.mcp-use.com/) to get started with mcp-use library
|
||||
- For the TypeScript version, visit [mcp-use-ts](https://github.com/mcp-use/mcp-use-ts)
|
||||
💡 Let your Python applications leverage the power of the Model Context Protocol with support for agents, clients, and advanced features.
|
||||
|
||||
| Supports | |
|
||||
| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
## 🏗️ What's Included
|
||||
|
||||
MCP-Use for Python provides three main capabilities:
|
||||
|
||||
- **🤖 MCP Agent** - Build AI agents that can use tools and reason across multiple steps
|
||||
- **🔌 MCP Client** - Connect directly to MCP servers for programmatic tool access
|
||||
- **🛠️ MCP Server** - _Coming soon!_ For now, use the [TypeScript version](../typescript/README.md#%EF%B8%8F-mcp-server-framework)
|
||||
|
||||
---
|
||||
|
||||
## 📖 Quick Links
|
||||
|
||||
- **[Main Repository](../../README.md)** - Overview of the entire MCP-Use ecosystem
|
||||
- **[TypeScript Version](../typescript/README.md)** - TypeScript implementation with server framework
|
||||
- **[Documentation](https://docs.mcp-use.com)** - Complete online documentation
|
||||
- **[Examples](./examples/)** - Python code examples
|
||||
|
||||
| Supports | |
|
||||
| :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Primitives** | [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) |
|
||||
| **Transports** | [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) |
|
||||
| **Transports** | [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) [](https://github.com/pietrozullo/mcp-use/actions/workflows/tests.yml) |
|
||||
|
||||
## Features
|
||||
|
||||
@@ -93,7 +97,13 @@
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
# Quick start
|
||||
---
|
||||
|
||||
# 🤖 MCP Agent
|
||||
|
||||
The **MCP Agent** is an AI-powered agent that can use tools from MCP servers to accomplish complex tasks. It reasons across multiple steps, selecting and executing tools as needed.
|
||||
|
||||
## Quick Start
|
||||
|
||||
With pip:
|
||||
|
||||
@@ -628,7 +638,13 @@ The `SandboxOptions` type provides configuration for the sandbox environment:
|
||||
- **Consistent environment**: Ensure consistent behavior across different systems
|
||||
- **Resource efficiency**: Offload resource-intensive tasks to cloud infrastructure
|
||||
|
||||
# Direct Tool Calls (Without LLM)
|
||||
---
|
||||
|
||||
# 🔌 MCP Client
|
||||
|
||||
The **MCP Client** allows you to connect directly to MCP servers and call tools programmatically without an AI agent. This is useful when you know exactly which tools to call and don't need AI reasoning.
|
||||
|
||||
## Direct Tool Calls (Without LLM)
|
||||
|
||||
You can call MCP server tools directly without an LLM when you need programmatic control:
|
||||
|
||||
@@ -705,6 +721,23 @@ if __name__ == "__main__":
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 🛠️ MCP Server
|
||||
|
||||
**Coming Soon!** Python support for creating MCP servers is under development.
|
||||
|
||||
In the meantime, you can create MCP servers using our [TypeScript implementation](../typescript/README.md#%EF%B8%8F-mcp-server-framework), which offers:
|
||||
|
||||
- Complete server framework with tools, resources, and prompts
|
||||
- Built-in inspector for debugging
|
||||
- React-based UI widgets for interactive experiences
|
||||
- Hot reload development workflow
|
||||
|
||||
Python agents and clients can connect to TypeScript servers seamlessly - the MCP protocol is language-agnostic.
|
||||
|
||||
---
|
||||
|
||||
# Debugging
|
||||
|
||||
MCP-Use provides a built-in debug mode that increases log verbosity and helps diagnose issues in your agent implementation.
|
||||
@@ -768,14 +801,6 @@ This is useful when you only need to see the agent's steps and decision-making p
|
||||
|
||||
We love contributions! Feel free to open issues for bugs or feature requests. Look at [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
||||
|
||||
## Contributors
|
||||
|
||||
Thanks to all our amazing contributors!
|
||||
|
||||
<a href="https://github.com/mcp-use/mcp-use/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=mcp-use/mcp-use" />
|
||||
</a>
|
||||
|
||||
## Top Starred Dependents
|
||||
|
||||
<!-- gh-dependents-info-used-by-start -->
|
||||
|
||||
+119
-31
@@ -21,20 +21,41 @@
|
||||
<strong>Build powerful AI agents, create MCP servers with UI widgets, and debug with built-in inspector - all in TypeScript</strong>
|
||||
</p>
|
||||
|
||||
> **📦 Part of the [MCP-Use Monorepo](../../README.md)** - This is the TypeScript implementation. Also available in [Python](../python/README.md).
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What is MCP-Use?
|
||||
|
||||
MCP-Use is a comprehensive TypeScript framework for building and using [Model Context Protocol (MCP)](https://modelcontextprotocol.io) applications. It provides everything you need to create AI agents that can use tools, build MCP servers with rich UI interfaces, and debug your applications with powerful developer tools.
|
||||
|
||||
## 🏗️ What's Included
|
||||
|
||||
MCP-Use for TypeScript provides the complete MCP stack:
|
||||
|
||||
- **🤖 MCP Agent** - Build AI agents that can use tools and reason across multiple steps
|
||||
- **🔌 MCP Client** - Connect directly to MCP servers for programmatic tool access
|
||||
- **🛠️ MCP Server Framework** - Create your own MCP servers with tools, resources, and prompts
|
||||
- **🎨 MCP-UI Resources** - Build ChatGPT-style apps with interactive React widgets
|
||||
- **🔍 MCP Inspector** - Web-based debugger for testing and monitoring
|
||||
|
||||
---
|
||||
|
||||
## 📖 Quick Links
|
||||
|
||||
- **[Main Repository](../../README.md)** - Overview of the entire MCP-Use ecosystem
|
||||
- **[Python Version](../python/README.md)** - Python implementation for agents and clients
|
||||
- **[Inspector Documentation](./packages/inspector/README.md)** - Debug your MCP servers
|
||||
- **[CLI Documentation](./packages/cli/README.md)** - Build tool for MCP apps
|
||||
|
||||
## 📦 Packages Overview
|
||||
|
||||
| Package | Description | Version | Downloads |
|
||||
|---------|-------------|---------|-----------|
|
||||
| **[mcp-use](#mcp-use-core-framework)** | Core framework for MCP clients and servers | [](https://www.npmjs.com/package/mcp-use) | [](https://www.npmjs.com/package/mcp-use) |
|
||||
| **[@mcp-use/cli](#mcp-use-cli)** | Build tool with hot reload and auto-inspector | [](https://www.npmjs.com/package/@mcp-use/cli) | [](https://www.npmjs.com/package/@mcp-use/cli) |
|
||||
| **[@mcp-use/inspector](#mcp-use-inspector)** | Web-based debugger for MCP servers | [](https://www.npmjs.com/package/@mcp-use/inspector) | [](https://www.npmjs.com/package/@mcp-use/inspector) |
|
||||
| **[create-mcp-use-app](#create-mcp-use-app)** | Project scaffolding tool | [](https://www.npmjs.com/package/create-mcp-use-app) | [](https://www.npmjs.com/package/create-mcp-use-app) |
|
||||
| Package | Description | Version | Downloads |
|
||||
| --------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||||
| **[mcp-use](#mcp-use-core-framework)** | Core framework for MCP clients and servers | [](https://www.npmjs.com/package/mcp-use) | [](https://www.npmjs.com/package/mcp-use) |
|
||||
| **[@mcp-use/cli](#mcp-use-cli)** | Build tool with hot reload and auto-inspector | [](https://www.npmjs.com/package/@mcp-use/cli) | [](https://www.npmjs.com/package/@mcp-use/cli) |
|
||||
| **[@mcp-use/inspector](#mcp-use-inspector)** | Web-based debugger for MCP servers | [](https://www.npmjs.com/package/@mcp-use/inspector) | [](https://www.npmjs.com/package/@mcp-use/inspector) |
|
||||
| **[create-mcp-use-app](#create-mcp-use-app)** | Project scaffolding tool | [](https://www.npmjs.com/package/create-mcp-use-app) | [](https://www.npmjs.com/package/create-mcp-use-app) |
|
||||
|
||||
---
|
||||
|
||||
@@ -57,6 +78,63 @@ Your MCP server is now running at `http://localhost:3000` with the inspector aut
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Build ChatGPT-Style Apps with MCP-UI Resources
|
||||
|
||||
One of the most powerful features of MCP-Use is the ability to build **interactive UI widgets** that work alongside your MCP tools. Create ChatGPT-like experiences with custom React components that can call MCP tools and display rich, interactive content.
|
||||
|
||||
### Why MCP-UI Resources?
|
||||
|
||||
- **🖥️ Interactive Interfaces** - Build rich UIs like dashboards, kanban boards, forms, and visualizations
|
||||
- **🔗 Tool Integration** - UI widgets can directly call MCP tools using the `useMcp()` hook
|
||||
- **📦 Self-Contained** - Widgets are bundled and served automatically by your MCP server
|
||||
- **🎯 Framework Agnostic** - Compatible with any MCP client (Claude Desktop, custom apps, etc.)
|
||||
- **⚡ Hot Reload** - Development workflow with instant updates
|
||||
|
||||
### Quick Example
|
||||
|
||||
```tsx
|
||||
// resources/analytics-dashboard.tsx
|
||||
import { useMcp } from 'mcp-use/react'
|
||||
import { useState, useEffect } from 'react'
|
||||
|
||||
export default function AnalyticsDashboard() {
|
||||
const { callTool } = useMcp()
|
||||
const [data, setData] = useState(null)
|
||||
|
||||
useEffect(() => {
|
||||
callTool('get_analytics', { period: '7d' }).then(setData)
|
||||
}, [])
|
||||
|
||||
return (
|
||||
<div className="dashboard">
|
||||
<h1>Analytics Dashboard</h1>
|
||||
<MetricsGrid data={data} />
|
||||
<Charts data={data} />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Then register it in your server:
|
||||
|
||||
```typescript
|
||||
server.uiResource({
|
||||
type: 'externalUrl',
|
||||
name: 'analytics-dashboard',
|
||||
widget: 'analytics-dashboard',
|
||||
title: 'Analytics Dashboard',
|
||||
description: 'Real-time analytics visualization',
|
||||
})
|
||||
```
|
||||
|
||||
**Learn More:**
|
||||
|
||||
- [MCP-UI Resources Guide](#mcp-ui-resources) (detailed section below)
|
||||
- [Create MCP-Use App](./packages/create-mcp-use-app/README.md) - Scaffolding with UI examples
|
||||
- [AI SDK Integration](#-ai-sdk-integration) - Build with Vercel AI SDK
|
||||
|
||||
---
|
||||
|
||||
## 📚 Package Documentation
|
||||
|
||||
### mcp-use: Core Framework
|
||||
@@ -76,21 +154,21 @@ const client = MCPClient.fromDict({
|
||||
mcpServers: {
|
||||
filesystem: {
|
||||
command: 'npx',
|
||||
args: ['@modelcontextprotocol/server-filesystem']
|
||||
args: ['@modelcontextprotocol/server-filesystem'],
|
||||
},
|
||||
github: {
|
||||
command: 'npx',
|
||||
args: ['@modelcontextprotocol/server-github'],
|
||||
env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN }
|
||||
}
|
||||
}
|
||||
env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
|
||||
},
|
||||
},
|
||||
})
|
||||
|
||||
// Create an AI agent
|
||||
const agent = new MCPAgent({
|
||||
llm: new ChatOpenAI({ model: 'gpt-4' }),
|
||||
client,
|
||||
maxSteps: 10
|
||||
maxSteps: 10,
|
||||
})
|
||||
|
||||
// Use the agent with natural language
|
||||
@@ -100,6 +178,7 @@ const result = await agent.run(
|
||||
```
|
||||
|
||||
**Key Client Features:**
|
||||
|
||||
- 🤖 **LLM Agnostic**: Works with OpenAI, Anthropic, Google, or any LangChain-supported LLM
|
||||
- 🔄 **Streaming Support**: Real-time streaming with `stream()` and `streamEvents()` methods
|
||||
- 🌐 **Multi-Server**: Connect to multiple MCP servers simultaneously
|
||||
@@ -118,7 +197,7 @@ import { z } from 'zod'
|
||||
// Create your MCP server
|
||||
const server = createMCPServer('weather-server', {
|
||||
version: '1.0.0',
|
||||
description: 'Weather information MCP server'
|
||||
description: 'Weather information MCP server',
|
||||
})
|
||||
|
||||
// Define tools with Zod schemas
|
||||
@@ -126,16 +205,16 @@ server.tool('get_weather', {
|
||||
description: 'Get current weather for a city',
|
||||
parameters: z.object({
|
||||
city: z.string().describe('City name'),
|
||||
units: z.enum(['celsius', 'fahrenheit']).optional()
|
||||
units: z.enum(['celsius', 'fahrenheit']).optional(),
|
||||
}),
|
||||
execute: async ({ city, units = 'celsius' }) => {
|
||||
const weather = await fetchWeather(city, units)
|
||||
return {
|
||||
temperature: weather.temp,
|
||||
condition: weather.condition,
|
||||
humidity: weather.humidity
|
||||
humidity: weather.humidity,
|
||||
}
|
||||
}
|
||||
},
|
||||
})
|
||||
|
||||
// Define resources
|
||||
@@ -145,7 +224,7 @@ server.resource('weather_map', {
|
||||
mimeType: 'text/html',
|
||||
fetch: async () => {
|
||||
return generateWeatherMapHTML()
|
||||
}
|
||||
},
|
||||
})
|
||||
|
||||
// Start the server
|
||||
@@ -155,6 +234,7 @@ server.listen(3000)
|
||||
```
|
||||
|
||||
**Key Server Features:**
|
||||
|
||||
- 🔍 **Auto Inspector**: Debugging UI automatically mounts at `/inspector`
|
||||
- 🎨 **UI Widgets**: Build React components served alongside MCP tools
|
||||
- 🔐 **OAuth Support**: Built-in authentication flow handling
|
||||
@@ -193,8 +273,7 @@ export default function AnalyticsDashboard() {
|
||||
const [data, setData] = useState(null)
|
||||
|
||||
useEffect(() => {
|
||||
callTool('get_analytics', { period: '7d' })
|
||||
.then(setData)
|
||||
callTool('get_analytics', { period: '7d' }).then(setData)
|
||||
}, [])
|
||||
|
||||
return (
|
||||
@@ -226,6 +305,7 @@ mcp-use start
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
|
||||
- 🚀 Auto-opens inspector in development mode
|
||||
- ♻️ Hot reload for both server and UI widgets
|
||||
- 📦 Bundles React widgets into standalone HTML pages
|
||||
@@ -256,6 +336,7 @@ mcp-use dev
|
||||
Web-based debugging tool for MCP servers - like Swagger UI but for MCP.
|
||||
|
||||
**Features:**
|
||||
|
||||
- 🔍 Test tools interactively with live execution
|
||||
- 📊 Monitor connection status and server health
|
||||
- 🔐 Handle OAuth flows automatically
|
||||
@@ -265,17 +346,20 @@ Web-based debugging tool for MCP servers - like Swagger UI but for MCP.
|
||||
**Three ways to use:**
|
||||
|
||||
1. **Automatic** (with mcp-use server):
|
||||
|
||||
```typescript
|
||||
server.listen(3000)
|
||||
// Inspector at http://localhost:3000/inspector
|
||||
```
|
||||
|
||||
2. **Standalone CLI**:
|
||||
|
||||
```bash
|
||||
npx mcp-inspect --url https://mcp.example.com/sse
|
||||
npx @mcp-use/inspector --url https://mcp.example.com/sse
|
||||
```
|
||||
|
||||
3. **Custom mounting**:
|
||||
|
||||
```typescript
|
||||
import { mountInspector } from '@mcp-use/inspector'
|
||||
mountInspector(app, '/debug')
|
||||
@@ -298,6 +382,7 @@ npx create-mcp-use-app my-app --template advanced
|
||||
```
|
||||
|
||||
**What you get:**
|
||||
|
||||
- ✅ Complete TypeScript setup
|
||||
- ✅ Pre-configured build scripts
|
||||
- ✅ Example tools and widgets
|
||||
@@ -320,10 +405,13 @@ const agent = new MCPAgent({
|
||||
mcpServers: {
|
||||
filesystem: {
|
||||
command: 'npx',
|
||||
args: ['@modelcontextprotocol/server-filesystem', '/Users/me/documents']
|
||||
}
|
||||
}
|
||||
})
|
||||
args: [
|
||||
'@modelcontextprotocol/server-filesystem',
|
||||
'/Users/me/documents',
|
||||
],
|
||||
},
|
||||
},
|
||||
}),
|
||||
})
|
||||
|
||||
// Natural language file operations
|
||||
@@ -340,14 +428,14 @@ const client = MCPClient.fromDict({
|
||||
mcpServers: {
|
||||
browser: { command: 'npx', args: ['@playwright/mcp'] },
|
||||
search: { command: 'npx', args: ['@mcp/server-search'] },
|
||||
memory: { command: 'npx', args: ['@mcp/server-memory'] }
|
||||
}
|
||||
memory: { command: 'npx', args: ['@mcp/server-memory'] },
|
||||
},
|
||||
})
|
||||
|
||||
const researcher = new MCPAgent({
|
||||
llm: new ChatAnthropic(),
|
||||
client,
|
||||
useServerManager: true // Auto-select appropriate server
|
||||
useServerManager: true, // Auto-select appropriate server
|
||||
})
|
||||
|
||||
// Complex research task
|
||||
@@ -362,26 +450,26 @@ const report = await researcher.run(`
|
||||
|
||||
```typescript
|
||||
const server = createMCPServer('db-admin', {
|
||||
version: '1.0.0'
|
||||
version: '1.0.0',
|
||||
})
|
||||
|
||||
server.tool('execute_query', {
|
||||
description: 'Execute SQL query safely',
|
||||
parameters: z.object({
|
||||
query: z.string(),
|
||||
database: z.string()
|
||||
database: z.string(),
|
||||
}),
|
||||
execute: async ({ query, database }) => {
|
||||
// Validate and execute query
|
||||
const results = await db.query(query, { database })
|
||||
return { rows: results, count: results.length }
|
||||
}
|
||||
},
|
||||
})
|
||||
|
||||
// Create an AI-powered DBA
|
||||
const dba = new MCPAgent({
|
||||
llm: new ChatOpenAI({ model: 'gpt-4' }),
|
||||
client: new MCPClient({ url: 'http://localhost:3000/mcp' })
|
||||
client: new MCPClient({ url: 'http://localhost:3000/mcp' }),
|
||||
})
|
||||
|
||||
await dba.run('Show me all users who signed up this week')
|
||||
@@ -517,4 +605,4 @@ MIT © [MCP-Use](https://github.com/mcp-use)
|
||||
|
||||
<p align="center">
|
||||
<strong>Built with ❤️ by the MCP-Use team</strong>
|
||||
</p>
|
||||
</p>
|
||||
|
||||
@@ -25,29 +25,29 @@
|
||||
|
||||
## 📦 Related Packages
|
||||
|
||||
| Package | Description | Version |
|
||||
|---------|-------------|---------|
|
||||
| [mcp-use](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/mcp-use) | Core MCP framework | [](https://www.npmjs.com/package/mcp-use) |
|
||||
| [@mcp-use/cli](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/cli) | Build tool for MCP apps | [](https://www.npmjs.com/package/@mcp-use/cli) |
|
||||
| [create-mcp-use-app](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/create-mcp-use-app) | Create MCP apps | [](https://www.npmjs.com/package/create-mcp-use-app) |
|
||||
| Package | Description | Version |
|
||||
| ------------------------------------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------- |
|
||||
| [mcp-use](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/mcp-use) | Core MCP framework | [](https://www.npmjs.com/package/mcp-use) |
|
||||
| [@mcp-use/cli](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/cli) | Build tool for MCP apps | [](https://www.npmjs.com/package/@mcp-use/cli) |
|
||||
| [create-mcp-use-app](https://github.com/mcp-use/mcp-use-ts/tree/main/packages/create-mcp-use-app) | Create MCP apps | [](https://www.npmjs.com/package/create-mcp-use-app) |
|
||||
|
||||
---
|
||||
|
||||
## ✨ Key Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **🚀 Auto-Mount** | Automatically available at `/inspector` for all MCP-Use servers |
|
||||
| **🔌 Multi-Connection** | Connect to and manage multiple MCP servers simultaneously |
|
||||
| **🎯 Interactive Testing** | Test tools with live execution and real-time results |
|
||||
| **📊 Real-time Status** | Monitor connection states, errors, and server health |
|
||||
| **🔐 OAuth Support** | Built-in OAuth flow handling with popup authentication |
|
||||
| **💾 Persistent Sessions** | Connections saved to localStorage and auto-reconnect |
|
||||
| **🎨 Beautiful UI** | Modern, responsive interface built with React and Tailwind |
|
||||
| **🔍 Tool Explorer** | Browse and execute all available tools with schema validation |
|
||||
| **📁 Resource Browser** | View and copy resource URIs with syntax highlighting |
|
||||
| **💬 Prompt Manager** | Test and manage prompts with argument templates |
|
||||
| **🌐 Universal Support** | Works with HTTP/SSE and WebSocket connections |
|
||||
| Feature | Description |
|
||||
| -------------------------- | --------------------------------------------------------------- |
|
||||
| **🚀 Auto-Mount** | Automatically available at `/inspector` for all MCP-Use servers |
|
||||
| **🔌 Multi-Connection** | Connect to and manage multiple MCP servers simultaneously |
|
||||
| **🎯 Interactive Testing** | Test tools with live execution and real-time results |
|
||||
| **📊 Real-time Status** | Monitor connection states, errors, and server health |
|
||||
| **🔐 OAuth Support** | Built-in OAuth flow handling with popup authentication |
|
||||
| **💾 Persistent Sessions** | Connections saved to localStorage and auto-reconnect |
|
||||
| **🎨 Beautiful UI** | Modern, responsive interface built with React and Tailwind |
|
||||
| **🔍 Tool Explorer** | Browse and execute all available tools with schema validation |
|
||||
| **📁 Resource Browser** | View and copy resource URIs with syntax highlighting |
|
||||
| **💬 Prompt Manager** | Test and manage prompts with argument templates |
|
||||
| **🌐 Universal Support** | Works with HTTP/SSE and WebSocket connections |
|
||||
|
||||
---
|
||||
|
||||
@@ -61,7 +61,7 @@ When you create an MCP server with `mcp-use`, the inspector is automatically ava
|
||||
import { createMCPServer } from 'mcp-use/server'
|
||||
|
||||
const server = createMCPServer('my-server', {
|
||||
version: '1.0.0'
|
||||
version: '1.0.0',
|
||||
})
|
||||
|
||||
// Add your tools, resources, prompts...
|
||||
@@ -72,6 +72,7 @@ server.listen(3000)
|
||||
```
|
||||
|
||||
**That's it!** No additional configuration needed. The inspector:
|
||||
|
||||
- Automatically mounts at `/inspector`
|
||||
- Auto-connects to your local MCP server
|
||||
- Provides instant debugging capabilities
|
||||
@@ -83,13 +84,13 @@ Use the inspector with any MCP server (local or remote):
|
||||
|
||||
```bash
|
||||
# Inspect a remote server
|
||||
npx mcp-inspect --url https://mcp.linear.app/sse
|
||||
npx @mcp-use/inspector --url https://mcp.linear.app/sse
|
||||
|
||||
# Custom port
|
||||
npx mcp-inspect --url http://localhost:3000/mcp --port 8080
|
||||
npx @mcp-use/inspector --url http://localhost:3000/mcp --port 8080
|
||||
|
||||
# Open inspector without auto-connect
|
||||
npx mcp-inspect
|
||||
npx @mcp-use/inspector
|
||||
```
|
||||
|
||||
### Method 3: Custom Integration
|
||||
@@ -116,6 +117,7 @@ app.listen(3000)
|
||||
### Dashboard Overview
|
||||
|
||||
The main dashboard shows:
|
||||
|
||||
- **Connection Overview**: Total servers, active connections, available tools
|
||||
- **Server List**: All configured servers with their current status
|
||||
- **Quick Actions**: Add new server, refresh all, clear sessions
|
||||
@@ -123,10 +125,12 @@ The main dashboard shows:
|
||||
### Adding Servers
|
||||
|
||||
Click "Add New MCP Server" and provide:
|
||||
|
||||
- **Server Name** (optional): Friendly name for identification
|
||||
- **Server URL**: The MCP endpoint URL
|
||||
|
||||
Example URLs:
|
||||
|
||||
- Local: `http://localhost:3000/mcp`
|
||||
- Linear: `https://mcp.linear.app/sse`
|
||||
- WebSocket: `ws://localhost:8080`
|
||||
@@ -135,15 +139,15 @@ Example URLs:
|
||||
|
||||
The inspector displays real-time connection states:
|
||||
|
||||
| State | Description | Action |
|
||||
|-------|-------------|---------|
|
||||
| 🔍 **discovering** | Finding the server | Wait |
|
||||
| 🔄 **connecting** | Establishing connection | Wait |
|
||||
| 🔐 **authenticating** | OAuth flow in progress | Complete auth |
|
||||
| 📥 **loading** | Loading tools & resources | Wait |
|
||||
| ✅ **ready** | Connected and operational | Use tools |
|
||||
| ❌ **failed** | Connection failed | Retry |
|
||||
| ⏳ **pending_auth** | Waiting for authentication | Click Authenticate |
|
||||
| State | Description | Action |
|
||||
| --------------------- | -------------------------- | ------------------ |
|
||||
| 🔍 **discovering** | Finding the server | Wait |
|
||||
| 🔄 **connecting** | Establishing connection | Wait |
|
||||
| 🔐 **authenticating** | OAuth flow in progress | Complete auth |
|
||||
| 📥 **loading** | Loading tools & resources | Wait |
|
||||
| ✅ **ready** | Connected and operational | Use tools |
|
||||
| ❌ **failed** | Connection failed | Retry |
|
||||
| ⏳ **pending_auth** | Waiting for authentication | Click Authenticate |
|
||||
|
||||
### Testing Tools
|
||||
|
||||
@@ -183,6 +187,7 @@ For servers requiring OAuth (like Linear):
|
||||
4. Connection automatically completes
|
||||
|
||||
If popup is blocked:
|
||||
|
||||
- Click "open auth page" link
|
||||
- Complete authentication manually
|
||||
- Return to inspector
|
||||
@@ -190,6 +195,7 @@ If popup is blocked:
|
||||
### Resource Management
|
||||
|
||||
Browse available resources:
|
||||
|
||||
- View resource descriptions
|
||||
- Copy resource URIs
|
||||
- Check MIME types
|
||||
@@ -198,6 +204,7 @@ Browse available resources:
|
||||
### Prompt Testing
|
||||
|
||||
Test prompts with the inspector:
|
||||
|
||||
1. Navigate to **Prompts** tab
|
||||
2. Select a prompt
|
||||
3. Fill in required arguments
|
||||
@@ -211,6 +218,7 @@ Test prompts with the inspector:
|
||||
### Server Card
|
||||
|
||||
Each server displays:
|
||||
|
||||
- Connection status indicator
|
||||
- Server name and URL
|
||||
- Available tools count
|
||||
@@ -220,6 +228,7 @@ Each server displays:
|
||||
### Tool Explorer
|
||||
|
||||
The tool explorer shows:
|
||||
|
||||
- Tool name and description
|
||||
- Input schema with types
|
||||
- Output schema
|
||||
@@ -229,6 +238,7 @@ The tool explorer shows:
|
||||
### Chat Interface
|
||||
|
||||
Interactive chat for testing conversational flows:
|
||||
|
||||
- Send messages to test prompts
|
||||
- View tool calls in real-time
|
||||
- See formatted responses
|
||||
@@ -251,6 +261,7 @@ Manage multiple servers efficiently:
|
||||
### Session Management
|
||||
|
||||
Sessions are automatically saved to localStorage:
|
||||
|
||||
- Preserves server configurations
|
||||
- Maintains connection preferences
|
||||
- Restores on page reload
|
||||
@@ -259,18 +270,19 @@ Sessions are automatically saved to localStorage:
|
||||
### Custom Themes
|
||||
|
||||
The inspector respects system theme preferences:
|
||||
|
||||
- Light mode for better readability
|
||||
- Dark mode for reduced eye strain
|
||||
- Automatic switching based on OS settings
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Cmd/Ctrl + K` | Quick server search |
|
||||
| `Cmd/Ctrl + N` | Add new server |
|
||||
| Shortcut | Action |
|
||||
| -------------- | ----------------------- |
|
||||
| `Cmd/Ctrl + K` | Quick server search |
|
||||
| `Cmd/Ctrl + N` | Add new server |
|
||||
| `Cmd/Ctrl + R` | Refresh all connections |
|
||||
| `Esc` | Close modals |
|
||||
| `Esc` | Close modals |
|
||||
|
||||
---
|
||||
|
||||
@@ -284,18 +296,18 @@ import { createMCPServer } from 'mcp-use/server'
|
||||
|
||||
const server = createMCPServer('dev-server', {
|
||||
version: '1.0.0',
|
||||
description: 'Development MCP Server'
|
||||
description: 'Development MCP Server',
|
||||
})
|
||||
|
||||
server.tool('debug_tool', {
|
||||
description: 'Debug tool for testing',
|
||||
parameters: z.object({
|
||||
message: z.string()
|
||||
message: z.string(),
|
||||
}),
|
||||
execute: async ({ message }) => {
|
||||
console.log('Debug:', message)
|
||||
return { received: message, timestamp: Date.now() }
|
||||
}
|
||||
},
|
||||
})
|
||||
|
||||
server.listen(3000)
|
||||
@@ -311,8 +323,8 @@ const server = createMCPServer('production-server', {
|
||||
clientId: process.env.OAUTH_CLIENT_ID,
|
||||
clientSecret: process.env.OAUTH_CLIENT_SECRET,
|
||||
authorizationUrl: 'https://api.example.com/oauth/authorize',
|
||||
tokenUrl: 'https://api.example.com/oauth/token'
|
||||
}
|
||||
tokenUrl: 'https://api.example.com/oauth/token',
|
||||
},
|
||||
})
|
||||
|
||||
// Inspector handles OAuth flow automatically
|
||||
@@ -341,6 +353,7 @@ URL: https://api.example.com/mcp
|
||||
The inspector is built with modern web technologies:
|
||||
|
||||
### Frontend Stack
|
||||
|
||||
- **React 19**: UI framework
|
||||
- **React Router**: Navigation
|
||||
- **Tailwind CSS**: Styling
|
||||
@@ -368,6 +381,7 @@ src/client/
|
||||
### Connection Management
|
||||
|
||||
The `useMcp` hook handles:
|
||||
|
||||
- WebSocket/SSE connections
|
||||
- Automatic reconnection
|
||||
- OAuth flow management
|
||||
@@ -381,6 +395,7 @@ The `useMcp` hook handles:
|
||||
### Common Issues and Solutions
|
||||
|
||||
**Inspector not loading:**
|
||||
|
||||
```bash
|
||||
# Check server is running
|
||||
curl http://localhost:3000/inspector
|
||||
@@ -390,23 +405,27 @@ curl http://localhost:3000/inspector
|
||||
```
|
||||
|
||||
**Connection fails immediately:**
|
||||
|
||||
- Check CORS configuration
|
||||
- Verify server URL is correct
|
||||
- Ensure server supports SSE/WebSocket
|
||||
- Check network/firewall settings
|
||||
|
||||
**OAuth popup blocked:**
|
||||
|
||||
- Allow popups for the inspector domain
|
||||
- Use the manual auth link provided
|
||||
- Check browser console for errors
|
||||
|
||||
**Tools not executing:**
|
||||
|
||||
- Verify tool schemas are valid
|
||||
- Check server logs for errors
|
||||
- Ensure proper authentication
|
||||
- Validate input parameters
|
||||
|
||||
**Session not persisting:**
|
||||
|
||||
- Check localStorage is enabled
|
||||
- Clear browser cache
|
||||
- Try incognito/private mode
|
||||
@@ -422,7 +441,7 @@ curl http://localhost:3000/inspector
|
||||
// Use pagination for many tools
|
||||
server.configurePagination({
|
||||
toolsPerPage: 50,
|
||||
enableSearch: true
|
||||
enableSearch: true,
|
||||
})
|
||||
```
|
||||
|
||||
@@ -433,7 +452,7 @@ server.configurePagination({
|
||||
const inspector = {
|
||||
maxConnections: 5,
|
||||
connectionTimeout: 30000,
|
||||
keepAlive: true
|
||||
keepAlive: true,
|
||||
}
|
||||
```
|
||||
|
||||
@@ -443,7 +462,7 @@ const inspector = {
|
||||
// Cache tool results
|
||||
server.enableCache({
|
||||
ttl: 300, // 5 minutes
|
||||
maxSize: 100 // MB
|
||||
maxSize: 100, // MB
|
||||
})
|
||||
```
|
||||
|
||||
@@ -457,7 +476,7 @@ server.enableCache({
|
||||
// Configure CORS for inspector access
|
||||
server.configureCORS({
|
||||
origin: ['http://localhost:3000'],
|
||||
credentials: true
|
||||
credentials: true,
|
||||
})
|
||||
```
|
||||
|
||||
@@ -474,7 +493,7 @@ server.use(authMiddleware)
|
||||
// Prevent abuse
|
||||
server.configureRateLimit({
|
||||
windowMs: 60000, // 1 minute
|
||||
max: 100 // requests
|
||||
max: 100, // requests
|
||||
})
|
||||
```
|
||||
|
||||
@@ -499,9 +518,9 @@ configureInspector(options: InspectorOptions): void
|
||||
|
||||
```typescript
|
||||
interface InspectorOptions {
|
||||
autoConnect?: boolean // Auto-connect to local server
|
||||
autoConnect?: boolean // Auto-connect to local server
|
||||
theme?: 'light' | 'dark' | 'auto'
|
||||
persistence?: boolean // Save sessions
|
||||
persistence?: boolean // Save sessions
|
||||
maxConnections?: number
|
||||
connectionTimeout?: number
|
||||
}
|
||||
@@ -512,6 +531,7 @@ interface InspectorOptions {
|
||||
## 🤝 Contributing
|
||||
|
||||
We welcome contributions! Areas for improvement:
|
||||
|
||||
- Additional UI themes
|
||||
- More keyboard shortcuts
|
||||
- Enhanced tool testing features
|
||||
@@ -534,4 +554,4 @@ See our [contributing guide](https://github.com/mcp-use/mcp-use-ts/blob/main/CON
|
||||
|
||||
## 📜 License
|
||||
|
||||
MIT © [MCP-Use](https://github.com/mcp-use)
|
||||
MIT © [MCP-Use](https://github.com/mcp-use)
|
||||
|
||||
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 7.6 KiB |
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 7.5 KiB |
@@ -0,0 +1 @@
|
||||
<?xml version="1.0" encoding="utf-8"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg version="1.1" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:cc="http://web.resource.org/cc/" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px" width="110px" height="110px" viewBox="0.21 -0.077 110 110" enable-background="new 0.21 -0.077 110 110" xml:space="preserve"><linearGradient id="SVGID_1_" gradientUnits="userSpaceOnUse" x1="63.8159" y1="56.6829" x2="118.4934" y2="1.8225" gradientTransform="matrix(1 0 0 -1 -53.2974 66.4321)"> <stop offset="0" style="stop-color:#387EB8"/> <stop offset="1" style="stop-color:#366994"/></linearGradient><path fill="url(#SVGID_1_)" d="M55.023-0.077c-25.971,0-26.25,10.081-26.25,12.156c0,3.148,0,12.594,0,12.594h26.75v3.781 c0,0-27.852,0-37.375,0c-7.949,0-17.938,4.833-17.938,26.25c0,19.673,7.792,27.281,15.656,27.281c2.335,0,9.344,0,9.344,0 s0-9.765,0-13.125c0-5.491,2.721-15.656,15.406-15.656c15.91,0,19.971,0,26.531,0c3.902,0,14.906-1.696,14.906-14.406 c0-13.452,0-17.89,0-24.219C82.054,11.426,81.515-0.077,55.023-0.077z M40.273,8.392c2.662,0,4.813,2.15,4.813,4.813 c0,2.661-2.151,4.813-4.813,4.813s-4.813-2.151-4.813-4.813C35.46,10.542,37.611,8.392,40.273,8.392z"/><linearGradient id="SVGID_2_" gradientUnits="userSpaceOnUse" x1="97.0444" y1="21.6321" x2="155.6665" y2="-34.5308" gradientTransform="matrix(1 0 0 -1 -53.2974 66.4321)"> <stop offset="0" style="stop-color:#FFE052"/> <stop offset="1" style="stop-color:#FFC331"/></linearGradient><path fill="url(#SVGID_2_)" d="M55.397,109.923c25.959,0,26.282-10.271,26.282-12.156c0-3.148,0-12.594,0-12.594H54.897v-3.781 c0,0,28.032,0,37.375,0c8.009,0,17.938-4.954,17.938-26.25c0-23.322-10.538-27.281-15.656-27.281c-2.336,0-9.344,0-9.344,0 s0,10.216,0,13.125c0,5.491-2.631,15.656-15.406,15.656c-15.91,0-19.476,0-26.532,0c-3.892,0-14.906,1.896-14.906,14.406 c0,14.475,0,18.265,0,24.219C28.366,100.497,31.562,109.923,55.397,109.923z M70.148,101.454c-2.662,0-4.813-2.151-4.813-4.813 s2.15-4.813,4.813-4.813c2.661,0,4.813,2.151,4.813,4.813S72.809,101.454,70.148,101.454z"/></svg>
|
||||
|
After Width: | Height: | Size: 2.2 KiB |
@@ -0,0 +1 @@
|
||||
<svg fill="none" height="512" viewBox="0 0 512 512" width="512" xmlns="http://www.w3.org/2000/svg"><rect fill="#3178c6" height="512" rx="50" width="512"/><rect fill="#3178c6" height="512" rx="50" width="512"/><path clip-rule="evenodd" d="m316.939 407.424v50.061c8.138 4.172 17.763 7.3 28.875 9.386s22.823 3.129 35.135 3.129c11.999 0 23.397-1.147 34.196-3.442 10.799-2.294 20.268-6.075 28.406-11.342 8.138-5.266 14.581-12.15 19.328-20.65s7.121-19.007 7.121-31.522c0-9.074-1.356-17.026-4.069-23.857s-6.625-12.906-11.738-18.225c-5.112-5.319-11.242-10.091-18.389-14.315s-15.207-8.213-24.18-11.967c-6.573-2.712-12.468-5.345-17.685-7.9-5.217-2.556-9.651-5.163-13.303-7.822-3.652-2.66-6.469-5.476-8.451-8.448-1.982-2.973-2.974-6.336-2.974-10.091 0-3.441.887-6.544 2.661-9.308s4.278-5.136 7.512-7.118c3.235-1.981 7.199-3.52 11.894-4.615 4.696-1.095 9.912-1.642 15.651-1.642 4.173 0 8.581.313 13.224.938 4.643.626 9.312 1.591 14.008 2.894 4.695 1.304 9.259 2.947 13.694 4.928 4.434 1.982 8.529 4.276 12.285 6.884v-46.776c-7.616-2.92-15.937-5.084-24.962-6.492s-19.381-2.112-31.066-2.112c-11.895 0-23.163 1.278-33.805 3.833s-20.006 6.544-28.093 11.967c-8.086 5.424-14.476 12.333-19.171 20.729-4.695 8.395-7.043 18.433-7.043 30.114 0 14.914 4.304 27.638 12.912 38.172 8.607 10.533 21.675 19.45 39.204 26.751 6.886 2.816 13.303 5.579 19.25 8.291s11.086 5.528 15.415 8.448c4.33 2.92 7.747 6.101 10.252 9.543 2.504 3.441 3.756 7.352 3.756 11.733 0 3.233-.783 6.231-2.348 8.995s-3.939 5.162-7.121 7.196-7.147 3.624-11.894 4.771c-4.748 1.148-10.303 1.721-16.668 1.721-10.851 0-21.597-1.903-32.24-5.71-10.642-3.806-20.502-9.516-29.579-17.13zm-84.159-123.342h64.22v-41.082h-179v41.082h63.906v182.918h50.874z" fill="#fff" fill-rule="evenodd"/></svg>
|
||||
|
After Width: | Height: | Size: 1.7 KiB |
Reference in New Issue
Block a user