mcp-tavily

# MCP Tavily [](https://smithery.ai/server/@kshern/mcp-tavily) [中文文档](./readme.zh-CN.md) A Model Context Protocol (MCP) server implementation for Tavily API, providing advanced search and content extraction capabilities. ## Features - **Multiple Search Tools**: - `search`: Basic search functionality with customizable options - `searchContext`: Context-aware search for better relevance - `searchQNA`: Question and answer focused search - **Content Extraction**: Extract content from URLs with configurable options - **Rich Configuration Options**: Extensive options for search depth, filtering, and content inclusion ### Usage with MCP Add the Tavily MCP server to your MCP configuration: ```json { "mcpServers": { "tavily": { "command": "npx", "args": ["-y", "@mcptools/mcp-tavily"], "env": { "TAVILY_API_KEY": "your-api-key" } } } } ``` > Note: Make sure to replace `your-api-key` with your actual Tavily API key. You can also set it as an environment variable `TAVILY_API_KEY` before running the server. ## API Reference ### Search Tools The server provides three search tools that can be called through MCP: #### 1. Basic Search ```typescript // Tool name: search { query: "artificial intelligence", options: { searchDepth: "advanced", topic: "news", maxResults: 10 } } ``` #### 2. Context Search ```typescript // Tool name: searchContext { query: "latest developments in AI", options: { topic: "news", timeRange: "week" } } ``` #### 3. Q&A Search ```typescript // Tool name: searchQNA { query: "What is quantum computing?", options: { includeAnswer: true, maxResults: 5 } } ``` ### Extract Tool ```typescript // Tool name: extract { urls: ["https://example.com/article1", "https://example.com/article2"], options: { extractDepth: "advanced", includeImages: true } } ``` ### Search Options All search tools share these options: ```typescript interface SearchOptions { searchDepth?: "basic" | "advanced"; // Search depth level topic?: "general" | "news" | "finance"; // Search topic category days?: number; // Number of days to search maxResults?: number; // Maximum number of results includeImages?: boolean; // Include images in results includeImageDescriptions?: boolean; // Include image descriptions includeAnswer?: boolean; // Include answer in results includeRawContent?: boolean; // Include raw content includeDomains?: string[]; // List of domains to include excludeDomains?: string[]; // List of domains to exclude maxTokens?: number; // Maximum number of tokens timeRange?: "year" | "month" | "week" | "day" | "y" | "m" | "w" | "d"; // Time range for search } ``` ### Extract Options ```typescript interface ExtractOptions { extractDepth?: "basic" | "advanced"; // Extraction depth level includeImages?: boolean; // Include images in results } ``` ## Response Format All tools return responses in the following format: ```typescript { content: Array<{ type: "text", text: string }> } ``` For search results, each item includes: - Title - Content - URL For extracted content, each item includes: - URL - Raw content - Failed URLs list (if any) ## Error Handling All tools include proper error handling and will throw descriptive error messages if something goes wrong. ## Installation ### Installing via Smithery To install Tavily API Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@kshern/mcp-tavily): ```bash npx -y @smithery/cli install @kshern/mcp-tavily --client claude ``` ### Manual Installation ```bash npm install @mcptools/mcp-tavily ``` Or use it directly with npx: ```bash npx @mcptools/mcp-tavily ``` ### Prerequisites - Node.js 16 or higher - npm or yarn - Tavily API key (get one from [Tavily](https://tavily.com)) ### Setup 1. Clone the repository 2. Install dependencies: ```bash npm install ``` 3. Set your Tavily API key: ```bash export TAVILY_API_KEY=your_api_key ``` ### Building ```bash npm run build ``` ## Debugging with MCP Inspector For development and debugging, we recommend using [MCP Inspector](https://github.com/modelcontextprotocol/inspector), a powerful development tool for MCP servers. The Inspector provides a user interface for: - Testing tool calls - Viewing server responses - Debugging tool execution - Monitoring server state ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. 1. Fork the repository 2. Create your feature branch (`git checkout -b feature/AmazingFeature`) 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) 4. Push to the branch (`git push origin feature/AmazingFeature`) 5. Open a Pull Request ## License This project is licensed under the MIT License. ## Support For any questions or issues: - Tavily API: refer to the [Tavily documentation](https://docs.tavily.com/) - MCP integration: refer to the [MCP documentation](https://modelcontextprotocol.io//)