Tavily MCP Server

A production-ready MCP (Model Context Protocol) server that provides web search capabilities using the Tavily API. This server integrates seamlessly with Roo and other MCP-compatible AI assistants.

Features

🔍 Web Search: Powerful web search using Tavily's AI-optimized search API
🎯 Direct Answers: Get immediate answers to queries when available
📊 Configurable Results: Control search depth, result count, and domain filtering
🚀 Production Ready: Built with TypeScript, comprehensive testing, and PM2 deployment
🔒 Secure: Environment-based API key management
📈 Monitoring: Full logging and process monitoring with PM2
🧪 Well Tested: Comprehensive unit and integration test coverage

Quick Start

Prerequisites

Node.js 18+
npm or yarn
Tavily API key (Get one here)
PM2 (for production deployment)

Installation & Deployment

Clone and setup:
```
cd tavily-mcp-server
npm install
```

Set your API key:

export TAVILY_API_KEY="your-api-key-here"

Run tests:
```
npm test
npm run test:coverage
```
Deploy with PM2:
```
./deploy.sh
```

That's it! The server is now running and ready for MCP connections.

Development

Build and Test

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run unit tests
npm test

# Run tests with coverage
npm run test:coverage

# Run integration tests
./test-mcp.js

# Lint code
npm run lint
npm run lint:fix

Testing

The project includes comprehensive testing:

Unit Tests: Test individual components and functions
Integration Tests: Test the complete MCP server functionality
MCP Protocol Tests: Validate MCP protocol compliance
API Tests: Test Tavily API integration (requires valid API key)

# Run all tests
npm test

# Run with coverage report
npm run test:coverage

# Test the actual MCP server
./test-mcp.js

Configuration

Environment Variables

TAVILY_API_KEY (required): Your Tavily API key
NODE_ENV (optional): Set to "production" for production deployment

PM2 Configuration

The pm2-apps.json file contains production configuration:

{
  "apps": [{
    "name": "tavily-mcp-server",
    "script": "dist/index.js",
    "instances": 1,
    "exec_mode": "fork",
    "env": {
      "NODE_ENV": "production",
      "TAVILY_API_KEY": "your-api-key"
    }
  }]
}

Usage with Roo

Global Installation

Add to your global MCP settings (~/.roo/mcp_settings.json):

{
  "mcpServers": {
    "tavily-search": {
      "command": "node",
      "args": ["/home/ubuntu/roo-tavily/tavily-mcp-server/dist/index.js"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Project-specific Installation

Add to your project's MCP settings (.roo/mcp.json):

{
  "mcpServers": {
    "tavily-search": {
      "command": "node",
      "args": ["./tavily-mcp-server/dist/index.js"],
      "env": {
        "TAVILY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Using the Web Search Tool

Once configured, you can use the web search tool in Roo:

<use_mcp_tool>
<server_name>tavily-search</server_name>
<tool_name>web_search</tool_name>
<arguments>
{
  "query": "latest developments in AI",
  "search_depth": "advanced",
  "max_results": 10,
  "include_answer": true
}
</arguments>
</use_mcp_tool>

API Reference

web_search Tool

Search the web using Tavily's AI-optimized search API.

Parameters

Parameter	Type	Required	Default	Description
`query`	string	✅	-	The search query to execute
`search_depth`	string	❌	"basic"	Search depth: "basic" or "advanced"
`include_answer`	boolean	❌	true	Whether to include a direct answer
`max_results`	number	❌	5	Number of results (1-20)
`include_domains`	string[]	❌	-	Domains to include in search
`exclude_domains`	string[]	❌	-	Domains to exclude from search

Response Format

The tool returns formatted search results including:

Direct Answer: AI-generated answer to the query (if available)
Search Results: List of relevant web pages with:
- Title and URL
- Content snippet
- Relevance score
- Publication date (if available)
Follow-up Questions: Suggested related queries

Example Response

# Search Results for: "latest developments in AI"

## Direct Answer
Recent AI developments include advances in large language models, 
multimodal AI systems, and improved reasoning capabilities...

## Search Results

### 1. Major AI Breakthroughs in 2024
**URL:** https://example.com/ai-breakthroughs
**Published:** 2024-01-15
**Score:** 0.95

Recent developments in artificial intelligence have shown remarkable 
progress in areas such as natural language processing...

---

### 2. OpenAI Announces GPT-5
**URL:** https://example.com/gpt5-announcement
**Score:** 0.92

OpenAI has announced the development of GPT-5, promising significant 
improvements in reasoning and multimodal capabilities...

---

## Follow-up Questions
1. What are the implications of these AI developments?
2. How do these advances compare to previous years?
3. What challenges remain in AI development?

Production Deployment

PM2 Management

# Start the server
pm2 start pm2-apps.json

# View status
pm2 status

# View logs
pm2 logs tavily-mcp-server

# Restart server
pm2 restart tavily-mcp-server

# Stop server
pm2 stop tavily-mcp-server

# Monitor all processes
pm2 monit

Nginx Reverse Proxy (Optional)

If you need HTTP access, you can set up an Nginx reverse proxy:

server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Monitoring and Logs

Application Logs: /var/log/pm2/tavily-mcp-server.log
Error Logs: /var/log/pm2/tavily-mcp-server-error.log
PM2 Monitoring: pm2 monit

Troubleshooting

Common Issues

"TAVILY_API_KEY environment variable is required"
- Ensure your API key is set: export TAVILY_API_KEY="your-key"
- Check PM2 config has the correct API key
"Cannot find module" errors
- Run npm install to install dependencies
- Ensure you've built the project: npm run build
Server won't start
- Check logs: pm2 logs tavily-mcp-server
- Verify API key is valid
- Ensure port is not in use
Search requests failing
- Verify API key is valid and has credits
- Check network connectivity
- Review error logs for specific API errors

Debug Mode

Run the server in debug mode:

NODE_ENV=development npm run dev

Testing Connection

Test the MCP server directly:

./test-mcp.js

Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Add tests for new functionality
Ensure all tests pass: npm test
Submit a pull request

License

MIT License - see LICENSE file for details.

Support

📧 Email: support@roo.com
🐛 Issues: GitHub Issues
📖 Documentation: Roo Documentation

Built with ❤️ by the Roo team