{"id":22542631,"url":"https://github.com/ramxx/mcp-tavily","last_synced_at":"2025-04-09T22:53:17.382Z","repository":{"id":265957324,"uuid":"896967375","full_name":"RamXX/mcp-tavily","owner":"RamXX","description":"An MCP server for Tavily's search API","archived":false,"fork":false,"pushed_at":"2025-04-04T16:45:25.000Z","size":129,"stargazers_count":46,"open_issues_count":2,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-09T22:53:11.786Z","etag":null,"topics":["mcp","news","search","tavily","web"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RamXX.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-01T18:34:28.000Z","updated_at":"2025-04-06T21:37:13.000Z","dependencies_parsed_at":"2024-12-27T23:35:55.095Z","dependency_job_id":"75504865-5e95-4ef1-8cae-782ba7f9ebc7","html_url":"https://github.com/RamXX/mcp-tavily","commit_stats":null,"previous_names":["ramxx/mcp-tavily"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RamXX%2Fmcp-tavily","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RamXX%2Fmcp-tavily/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RamXX%2Fmcp-tavily/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RamXX%2Fmcp-tavily/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RamXX","download_url":"https://codeload.github.com/RamXX/mcp-tavily/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248125636,"owners_count":21051766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","news","search","tavily","web"],"created_at":"2024-12-07T13:11:48.346Z","updated_at":"2025-04-09T22:53:17.370Z","avatar_url":"https://github.com/RamXX.png","language":"Python","funding_links":[],"categories":["Search \u0026 Data Extraction"],"sub_categories":["How to Submit"],"readme":"# Tavily MCP Server\n\nA Model Context Protocol server that provides AI-powered web search capabilities using Tavily's search API. This server enables LLMs to perform sophisticated web searches, get direct answers to questions, and search recent news articles with AI-extracted relevant content.\n\n## Features\n\n### Available Tools\n\n- `tavily_web_search` - Performs comprehensive web searches with AI-powered content extraction.\n\n  - `query` (string, required): Search query\n  - `max_results` (integer, optional): Maximum number of results to return (default: 5, max: 20)\n  - `search_depth` (string, optional): Either \"basic\" or \"advanced\" search depth (default: \"basic\")\n  - `include_domains` (list or string, optional): List of domains to specifically include in results\n  - `exclude_domains` (list or string, optional): List of domains to exclude from results\n\n- `tavily_answer_search` - Performs web searches and generates direct answers with supporting evidence.\n\n  - `query` (string, required): Search query\n  - `max_results` (integer, optional): Maximum number of results to return (default: 5, max: 20)\n  - `search_depth` (string, optional): Either \"basic\" or \"advanced\" search depth (default: \"advanced\")\n  - `include_domains` (list or string, optional): List of domains to specifically include in results\n  - `exclude_domains` (list or string, optional): List of domains to exclude from results\n\n- `tavily_news_search` - Searches recent news articles with publication dates.\n  - `query` (string, required): Search query\n  - `max_results` (integer, optional): Maximum number of results to return (default: 5, max: 20)\n  - `days` (integer, optional): Number of days back to search (default: 3)\n  - `include_domains` (list or string, optional): List of domains to specifically include in results\n  - `exclude_domains` (list or string, optional): List of domains to exclude from results\n\n### Prompts\n\nThe server also provides prompt templates for each search type:\n\n- **tavily_web_search** - Search the web using Tavily's AI-powered search engine\n- **tavily_answer_search** - Search the web and get an AI-generated answer with supporting evidence\n- **tavily_news_search** - Search recent news articles with Tavily's news search\n\n## Prerequisites\n\n- Python 3.11 or later\n- A Tavily API key (obtain from [Tavily's website](https://tavily.com))\n- `uv` Python package manager (recommended)\n\n## Installation\n\n### Option 1: Using pip or uv\n\n```bash\n# With pip\npip install mcp-tavily\n\n# Or with uv (recommended)\nuv add mcp-tavily\n```\n\nYou should see output similar to:\n\n```\nResolved packages: mcp-tavily, mcp, pydantic, python-dotenv, tavily-python [...]\nSuccessfully installed mcp-tavily-0.1.4 mcp-1.0.0 [...]\n```\n\n### Option 2: From source\n\n```bash\n# Clone the repository\ngit clone https://github.com/RamXX/mcp-tavily.git\ncd mcp-tavily\n\n# Create a virtual environment (optional but recommended)\npython -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install dependencies and build\nuv sync  # Or: pip install -r requirements.txt\nuv build  # Or: pip install -e .\n\n# To install with test dependencies:\nuv sync --dev  # Or: pip install -r requirements-dev.txt\n```\n\nDuring installation, you should see the package being built and installed with its dependencies.\n\n### Usage with VS Code\n\nFor quick installation, use one of the one-click install buttons below:\n\n[![Install with UV in VS Code](https://img.shields.io/badge/VS_Code-UV-0098FF?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=tavily\u0026inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Tavily%20API%20Key%22%2C%22password%22%3Atrue%7D%5D\u0026config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-tavily%22%5D%2C%22env%22%3A%7B%22TAVILY_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D) [![Install with UV in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-UV-24bfa5?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=tavily\u0026inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22apiKey%22%2C%22description%22%3A%22Tavily%20API%20Key%22%2C%22password%22%3Atrue%7D%5D\u0026config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-tavily%22%5D%2C%22env%22%3A%7B%22TAVILY_API_KEY%22%3A%22%24%7Binput%3AapiKey%7D%22%7D%7D\u0026quality=insiders)\n\nFor manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`.\n\nOptionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.\n\n\u003e Note that the `mcp` key is not needed in the `.vscode/mcp.json` file.\n\n```json\n{\n  \"mcp\": {\n    \"inputs\": [\n      {\n        \"type\": \"promptString\",\n        \"id\": \"apiKey\",\n        \"description\": \"Tavily API Key\",\n        \"password\": true\n      }\n    ],\n    \"servers\": {\n      \"tavily\": {\n        \"command\": \"uvx\",\n        \"args\": [\"mcp-tavily\"],\n        \"env\": {\n          \"TAVILY_API_KEY\": \"${input:apiKey}\"\n        }\n      }\n    }\n  }\n}\n```\n\n## Configuration\n\n### API Key Setup\n\nThe server requires a Tavily API key, which can be provided in three ways:\n\n1. Through a `.env` file in your project directory:\n\n   ```\n   TAVILY_API_KEY=your_api_key_here\n   ```\n\n2. As an environment variable:\n\n   ```bash\n   export TAVILY_API_KEY=your_api_key_here\n   ```\n\n3. As a command-line argument:\n   ```bash\n   python -m mcp_server_tavily --api-key=your_api_key_here\n   ```\n\n### Configure for Claude.app\n\nAdd to your Claude settings:\n\n```json\n\"mcpServers\": {\n  \"tavily\": {\n    \"command\": \"python\",\n    \"args\": [\"-m\", \"mcp_server_tavily\"]\n  },\n  \"env\": {\n    \"TAVILY_API_KEY\": \"your_api_key_here\"\n  }\n}\n```\n\nIf you encounter issues, you may need to specify the full path to your Python interpreter. Run `which python` to find the exact path.\n\n## Usage Examples\n\nFor a regular web search:\n\n```\nTell me about Anthropic's newly released MCP protocol\n```\n\nTo generate a report with domain filtering:\n\n```\nTell me about redwood trees. Please use MLA format in markdown syntax and include the URLs in the citations. Exclude Wikipedia sources.\n```\n\nTo use answer search mode for direct answers:\n\n```\nI want a concrete answer backed by current web sources: What is the average lifespan of redwood trees?\n```\n\nFor news search:\n\n```\nGive me the top 10 AI-related news in the last 5 days\n```\n\n## Testing\n\nThe project includes a comprehensive test suite. To run the tests:\n\n1. Install test dependencies:\n\n   ```bash\n   source .venv/bin/activate  # If using a virtual environment\n   uv sync --dev  # Or: pip install -r requirements-dev.txt\n   ```\n\n2. Run the tests:\n   ```bash\n   ./tests/run_tests.sh\n   ```\n\nYou should see output similar to:\n\n```\n============================= test session starts ==============================\ncollected 27 items\n\ntests/test_models.py ................. [ 62%]\ntests/test_utils.py ..... [ 81%]\ntests/test_integration.py ..... [100%]\n\n---------- coverage: platform darwin, python 3.13.2-final-0 ----------\nName                                Stmts   Miss  Cover\n-------------------------------------------------------\nsrc/mcp_server_tavily/__init__.py      16      2    88%\nsrc/mcp_server_tavily/__main__.py       2      2     0%\nsrc/mcp_server_tavily/server.py       137     80    42%\n-------------------------------------------------------\nTOTAL                                 155     84    46%\n\n\n============================== 27 passed in 0.40s ==============================\n```\n\nThe test suite includes tests for data models, utility functions, integration testing, error handling, and parameter validation. It focuses on verifying that all API capabilities work correctly, including handling of domain filters and various input formats.\n\n## Debugging\n\nYou can use the MCP inspector to debug the server:\n\n```bash\n# Using npx\nnpx @modelcontextprotocol/inspector python -m mcp_server_tavily\n\n# For development\ncd path/to/mcp-tavily\nnpx @modelcontextprotocol/inspector python -m mcp_server_tavily\n```\n\n## Contributing\n\nWe welcome contributions to improve mcp-tavily! Here's how you can help:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run tests to ensure they pass\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\nFor examples of other MCP servers and implementation patterns, see:\nhttps://github.com/modelcontextprotocol/servers\n\n## License\n\nmcp-tavily is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framxx%2Fmcp-tavily","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Framxx%2Fmcp-tavily","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Framxx%2Fmcp-tavily/lists"}