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

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