Tavily Search MCP server

This MCP server leverages the Tavily API to provide AI-powered search capabilities for AI assistants. It allows assistants to perform web searches and retrieve relevant, up-to-date information with features like search depths, rich search results, AI-generated summaries, and comprehensive search history storage.

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

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:

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

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

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

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.