Tavily MCP Server
A Model Context Protocol (MCP) server that provides AI-powered search capabilities using the Tavily API. This server enables AI assistants to perform comprehensive web searches and retrieve relevant, up-to-date information.
Features
- AI-powered search functionality
- Support for basic and advanced search depths
- Rich search results including titles, URLs, and content snippets
- AI-generated summaries of search results
- Result scoring and response time tracking
- Comprehensive search history storage with caching
- MCP Resources for flexible data access
Prerequisites
- Node.js (v16 or higher)
- npm (Node Package Manager)
- Tavily API key (Get one at Tavily's website)
- An MCP client (e.g., Cline, Claude Desktop, or your own implementation)
Installation
- Clone the repository:
git clone https://github.com/it-beard/tavily-server.git
cd tavily-mcp-server
- Install dependencies:
- Build the project:
Configuration
This server can be used with any MCP client. Below are configuration instructions for popular clients:
Cline Configuration
If you're using Cline (the VSCode extension for Claude), create or modify the MCP settings file at:
- macOS:
~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Windows:
%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
- Linux:
~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Add the following configuration (replace paths and API key with your own):
{
"mcpServers": {
"tavily": {
"command": "node",
"args": ["/path/to/tavily-server/build/index.js"],
"env": {
"TAVILY_API_KEY": "your-api-key-here"
}
}
}
}
Claude Desktop Configuration
If you're using the Claude Desktop app, modify the configuration file at:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
Use the same configuration format as shown above.
Other MCP Clients
For other MCP clients, consult their documentation for the correct configuration file location and format. The server configuration should include:
- Command to run the server (typically
node)
- Path to the compiled server file
- Environment variables including the Tavily API key
Usage
Tools
The server provides a single tool named search with the following parameters:
Required Parameters
query (string): The search query to execute
Optional Parameters
search_depth (string): Either "basic" (faster) or "advanced" (more comprehensive)
Example Usage
// Example using the MCP SDK
const result = await mcpClient.callTool("tavily", "search", {
query: "latest developments in artificial intelligence",
search_depth: "basic"
});
Resources
The server provides both static and dynamic resources for flexible data access:
Static Resources
tavily://last-search/result: Returns the results of the most recent search query
- Persisted to disk in the data directory
- Survives server restarts
- Returns a 'No search has been performed yet' error if no search has been done
Dynamic Resources (Resource Templates)
tavily://search/{query}: Access search results for any query
- Replace {query} with your URL-encoded search term
- Example:
tavily://search/artificial%20intelligence
- Returns cached results if the query was previously made
- Performs and stores new search if query hasn't been searched before
- Returns the same format as the search tool but through a resource interface
Resources in MCP provide an alternative way to access data compared to tools:
- Tools are for executing operations (like performing a new search)
- Resources are for accessing data (like retrieving existing search results)
- Resource URIs can be stored and accessed later
- Resources support both static (fixed) and dynamic (templated) access patterns
Response Format
interface SearchResponse {
query: string;
answer: string;
results: Array;
response_time: number;
}
Persistent Storage
The server implements comprehensive persistent storage for search results:
Storage Location
- Data is stored in the
data directory
data/searches.json contains all historical search results- Data persists between server restarts
- Storage is automatically initialized on server start
Storage Features
- Stores complete search history
- Caches all search results for quick retrieval
- Automatic saving of new search results
- Disk-based persistence
- JSON format for easy debugging
- Error handling for storage operations
- Automatic directory creation
Caching Behavior
- All search results are cached automatically
- Subsequent requests for the same query return cached results
- Caching improves response time and reduces API calls
- Cache persists between server restarts
- Last search is tracked for quick access
Development
Project Structure
tavily-server/
├── src/
│ └── index.ts # Main server implementation
├── data/ # Persistent storage directory
│ └── searches.json # Search history and cache storage
├── build/ # Compiled JavaScript files
├── package.json # Project dependencies and scripts
└── tsconfig.json # TypeScript configuration
Available Scripts
npm run build: Compile TypeScript and make the output executablenpm run start: Start the MCP server (after building)npm run dev: Run the server in development mode
Error Handling
The server provides detailed error messages for common issues:
- Invalid API key
- Network errors
- Invalid search parameters
- API rate limiting
- Resource not found
- Invalid resource URIs
- Storage read/write errors
Contributing
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add some amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
