Content
# Tool List
> A server based on [MCP (Model Context Protocol)](https://modelcontextprotocol.io/), using the official FastMCP SDK.
[](https://python.org)
[](https://modelcontextprotocol.io/)
[](LICENSE)
[](https://smithery.ai/server/@HundunOnline/mcp-metaso)
## ✨ Features
- 🔍 **Multi-dimensional Search**: Supports six search types: webpage, document, scholar, image, video, and podcast
- 📄 **Webpage Parsing**: Extracts webpage content and converts it to Markdown or JSON format
- ⚡ **High Performance**: Based on FastMCP SDK, asynchronous processing, and type safety
- 🔌 **Standard Compatibility**: Fully compliant with MCP protocol specifications, can be integrated with Claude Desktop and other clients
## 🚀 Quick Start
### Install Dependencies
#### Installing via Smithery
To install mcp-metaso for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@HundunOnline/mcp-metaso):
```bash
npx -y @smithery/cli install @HundunOnline/mcp-metaso --client claude
```
#### Manual Installation
```bash
pip install -r requirements.txt
```
### Configure API Key
```bash
export METASO_API_KEY="your-api-key-here"
```
### Start Server
```bash
python server.py
```
### Test Features
```bash
python test_all_scopes.py
```
## 🔧 Claude Desktop Integration
### DXT Extension Installation (Simplest Way) 🌟
Claude Desktop now supports DXT extension format, making installation as easy as installing a browser extension!
1. **Download DXT Extension File**
- Download `mcp-metaso-1.1.0.dxt` from the [release page](https://github.com/HundunOnline/mcp-metaso/releases)
2. **Double-click to Install**
- Open Claude Desktop application
- Navigate to **Settings > Extensions**
- Click "Install from .dxt file" and select the downloaded file
- Enter your Metaso API key in the configuration interface
- Click "Install" to complete
3. **Use Immediately**
- Restart Claude Desktop
- Start using: "Search for the latest developments in artificial intelligence"
### Automatic Installation Tool (Traditional Way)
If you prefer the traditional installation method:
```bash
# Automatically install to Claude Desktop
python tools/install_claude.py
# Or use the configuration generator
python tools/claude_config_generator.py --save
```
### Manual Configuration
Add the following to the Claude Desktop configuration file:
```json
{
"mcpServers": {
"mcp-metaso": {
"command": "python",
"args": ["/path/to/mcp-metaso/server.py"],
"env": {
"METASO_API_KEY": "your-api-key-here"
}
}
}
}
```
**Configuration File Location:**
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
### Verify Configuration
After installation, verify that the configuration is correct:
```bash
# Verify MCP server configuration
python tools/validate_config.py
# Generate a diagnostic report
python tools/validate_config.py --report
```
### Troubleshooting
If Claude Desktop does not display the 🔨 icon:
1. **Restart Claude Desktop** - Configuration changes require a restart of the application
2. **Check Path** - Ensure an absolute path is used to point to server.py
3. **Verify API Key** - Ensure METASO_API_KEY is set correctly
4. **Check Logs** - Check for error messages in the Claude Desktop logs folder
**Common Tool Commands:**
```bash
# Generate configuration
python tools/claude_config_generator.py --api-key your_key --save
# Automatic installation
python tools/install_claude.py --auto-confirm
# Uninstall server
python tools/install_claude.py --uninstall
# Verify configuration
python tools/validate_config.py
# Use the launcher
python tools/launcher.py
```
## 📖 Available Tools
### metaso_search
Multi-dimensional search tool, supporting six search types:
```python
metaso_search(
query="Artificial intelligence development trends", # Search query
scope="webpage", # Search type: webpage/document/scholar/image/video/podcast
include_summary=False, # Include AI summary
size=10 # Result count (1-20)
)
```
**Search Type Description:**
- `webpage` - Webpage search: news, blogs, information
- `document` - Document search: PDF documents, technical documents
- `scholar` - Scholar search: papers, research literature
- `image` - Image search: images, charts, illustrations
- `video` - Video search: tutorials, lectures, entertainment content
- `podcast` - Podcast search: audio programs, interviews
### metaso_reader
Webpage content parsing tool:
```python
metaso_reader(
url="https://example.com", # Webpage URL
output_format="markdown" # Output format: markdown/json
)
```
## 📁 Project Structure
```
mcp-metaso/
├── server.py # Main server implementation (FastMCP)
├── config.py # Configuration management
├── tools/ # Claude Desktop integration tools
│ ├── __init__.py # Tool package initialization
│ ├── claude_config_generator.py # Claude configuration generator
│ ├── install_claude.py # Automatic installation script
│ ├── validate_config.py # Configuration validation tool
│ └── launcher.py # Launcher
├── test_all_scopes.py # Feature test script
├── requirements.txt # Project dependencies
├── setup.py # Package installation configuration
└── README.md # Project description
```
## 🔨 Development
### Environment Requirements
- Python 3.10+
- Metaso API Key
### Local Development
1. Clone the project:
```bash
git clone https://github.com/HundunOnline/mcp-metaso
cd mcp-metaso
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Set environment variables:
```bash
export METASO_API_KEY="your-key"
```
4. Run tests:
```bash
python test_all_scopes.py
```
### Custom DXT Extension
Developers can customize DXT extension packages:
```bash
# Build DXT extension package
python build-dxt.py
# This will generate:
# - mcp-metaso-1.1.0.dxt (extension package)
# - DXT Installation Guide.md (user installation instructions)
```
### Add New Features
Use the FastMCP decorator to easily add new tools:
```python
@mcp.tool()
async def new_tool(param: str) -> str:
"""New tool description
Args:
param: Parameter description
"""
# Implementation logic
return result
```
## 📄 License
This project is licensed under the [MIT License](LICENSE).
## 🤝 Contribution
Welcome to submit issues and pull requests!
## 🔗 Related Links
- [MCP Official Documentation](https://modelcontextprotocol.io/)
- [FastMCP SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Metaso AI](https://metaso.cn/)
