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

1. Clone and setup:

   cd tavily-mcp-server
   npm install
   

2. Set your API key:

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

3. Run tests:

   npm test
   npm run test:coverage
   

4. 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

1. "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

2. "Cannot find module" errors

   • Run npm install to install dependencies
   • Ensure you've built the project: npm run build

3. Server won't start

   • Check logs: pm2 logs tavily-mcp-server
   • Verify API key is valid
   • Ensure port is not in use

4. 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

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass: npm test
6. 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