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:

npm install

Build the project:

npm run build

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 intelligence
- 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<{
    title: string;
    url: string;
    content: string;
    score: number;
  }>;
  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 executable
npm 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

Model Context Protocol (MCP) for the server framework
Tavily API for providing the search capabilities

Tavily MCP Server

Integrations