Exa Web Search MCP server

ReActMCP Web Search is a Model Context Protocol (MCP) server that enhances AI assistants with real-time web search capabilities. It uses the Exa API to perform both basic and advanced web searches, returning markdown-formatted results that include titles, URLs, publication dates, and content summaries.

Requirements

• Python 3.8+
• python-dotenv
• exa_py
• Additional dependencies required by your MCP framework

Installation

1. Clone the Repository

   git clone https://github.com/mshojaei77/ReActMCP.git
   cd ReActMCP
   

2. Create a Virtual Environment

   python -m venv venv
   source venv/bin/activate  # On Windows use: venv\Scripts\activate
   

3. Install Dependencies

   pip install -r requirements.txt
   

Configuration

Environment Variables

Create a .env file in the project root directory:

EXA_API_KEY=your_exa_api_key_here
OPENAI_API_KEY=...

MCP Configuration

The mcp_config.json file defines the settings and available tools:

{
  "websearch": {
    "script": "web_search.py",
    "encoding_error_handler": "ignore",
    "description": "Web search capability using Exa API that provides real-time internet search results. Supports both basic and advanced search with filtering options including domain restrictions, text inclusion requirements, and date filtering. Returns formatted results with titles, URLs, publication dates, and content summaries.",
    "required_env_vars": ["EXA_API_KEY"],
    "active": true
  },
  "settings": {
    "model": "gpt-4o",
    "system_prompt_path": "system_prompt.txt"
  }
}

System Prompt

The system_prompt.txt file configures your AI assistant's behavior. You can customize this file to adjust the tone and capabilities of your assistant.

Usage

Running the Web Search Server

To start the MCP server:

python servers/web_search.py

This exposes two main tools:

• search_web: For basic web searches
• advanced_search_web: For advanced searches with filtering options

Testing the Tools

You can test the search functionality by uncommenting the test function in web_search.py:

if __name__ == "__main__":
    import asyncio
    # Uncomment the following line to perform a test search
    # asyncio.run(test_search())
    mcp.run()

Claude Desktop Configuration

Add this server to Claude Desktop by including in your configuration:

{
  "mcpServers": {
    "websearch": {
         "command": "python",
         "args": ["path/to/servers/exa_web_search.py"]
       }
  }
}

Troubleshooting

• Missing EXA_API_KEY: Ensure your .env file contains a valid Exa API key
• Dependency Issues: Verify all required Python packages are installed
• API Errors: Check your network connection and the Exa API status

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "websearch" '{"command":"python","args":["path/to/servers/exa_web_search.py"]}'

See the official Claude Code MCP documentation for more details.

For 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 > Tools & Integrations and click "New MCP Server".

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

{
    "mcpServers": {
        "websearch": {
            "command": "python",
            "args": [
                "path/to/servers/exa_web_search.py"
            ]
        }
    }
}

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 explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "websearch": {
            "command": "python",
            "args": [
                "path/to/servers/exa_web_search.py"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect