tavily 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

1. Clone the repository:

   git clone https://github.com/it-beard/tavily-server.git
   cd tavily-mcp-server

2. Install dependencies:

   npm install

3. 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%CursorUserglobalStoragesaoudrizwan.claude-devsettingscline_mcp_settings.json - Linux: ~/.config/Cursor/User/globalStorage/saoudrizwan.claude-devsettingscline_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%Claudeclaude_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: 1. Command to run the server (typically node) 2. Path to the compiled server file 3. 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<{
    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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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