This is a fork of https://github.com/exa-labs/exa-mcp-server.

# Exa MCP Server 🔍
[![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=exa&config=eyJuYW1lIjoiZXhhIiwidHlwZSI6Imh0dHAiLCJ1cmwiOiJodHRwczovL21jcC5leGEuYWkvbWNwIn0=)
[![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=exa&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.exa.ai%2Fmcp%22%7D)
[![npm version](https://badge.fury.io/js/jordy-exa-mcp-server.svg)](https://www.npmjs.com/package/jordy-exa-mcp-server)

## Exa Code: fast, efficient web context for coding agents

Vibe coding should never have a bad vibe. `exa-code` is a huge step towards coding agents that never hallucinate.

When your coding agent makes a search query, `exa-code` searches over billions
of Github repos, docs pages, Stackoverflow posts, and more, to find the perfect, token-efficient context that the agent needs to code correctly. It's powered by the Exa search engine.

Examples of queries you can make with `exa-code`:
* use Exa search in python and make sure content is always livecrawled
* use correct syntax for vercel ai sdk to call gpt-5 nano asking it how are you
* how to set up a reproducible Nix Rust development environment

**✨ Works with Cursor and Claude Code!** Use the HTTP-based configuration format:

```json
{
  "mcpServers": {
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp",
      "headers": {}
    }
  }
}
```

You can enable specific tool(s) using the `tools` parameter (if multiple, then with a comma-separated list):
```
https://mcp.exa.ai/mcp?tools=web_search_exa,get_code_context_exa
```

Or enable all tools:
```
https://mcp.exa.ai/mcp?tools=web_search_exa,deep_search_exa,get_code_context_exa,crawling_exa,company_research_exa,linkedin_search_exa,deep_researcher_start,deep_researcher_check
```

You may include your exa api key in the url like this:
```
https://mcp.exa.ai/mcp?exaApiKey=YOUREXAKEY
```

**Note:** By default, only `web_search_exa` and `get_code_context_exa` are enabled. Add other tools as needed using the `tools` parameter.

---

A Model Context Protocol (MCP) server that connects AI assistants like Claude to Exa AI's search capabilities, including web search, research tools, and our new code search feature.

## Remote Exa MCP 🌐

Connect directly to Exa's hosted MCP server (instead of running it locally).

### Remote Exa MCP URL

```
https://mcp.exa.ai/mcp
```

### Claude Desktop Configuration for Remote MCP

Add this to your Claude Desktop configuration file:

```json
{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.exa.ai/mcp"
      ]
    }
  }
}
```

### Cursor and Claude Code Configuration for Remote MCP

For Cursor and Claude Code, use this HTTP-based configuration format:

```json
{
  "mcpServers": {
    "exa": {
      "type": "http",
      "url": "https://mcp.exa.ai/mcp",
      "headers": {}
    }
  }
}
```

### Codex Configuration for Remote MCP

Open your Codex configuration file:

```bash
code ~/.codex/config.toml
```

Add this configuration:

```toml
[mcp_servers.exa]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"]
env = { EXA_API_KEY = "your-api-key-here" }
```

Replace `your-api-key-here` with your actual Exa API key from [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys).

### Claude Code Plugin

The easiest way to get started with Exa in Claude Code, using plugins:

```bash
# Add the Exa marketplace
/plugin marketplace add exa-labs/exa-mcp-server

# Install the plugin
/plugin install exa-mcp-server
```

Then set your API key:
```bash
export EXA_API_KEY="your-api-key-here"
```

Get your API key from [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys).

### NPM Installation

```bash
npm install -g jordy-exa-mcp-server
```

### Using Claude Code

```bash
claude mcp add exa -e EXA_API_KEY=YOUR_API_KEY -- npx -y jordy-exa-mcp-server
```

## Configuration ⚙️

### 1. Configure Claude Desktop to recognize the Exa MCP server

You can find claude_desktop_config.json inside the settings of Claude Desktop app:

Open the Claude Desktop app and enable Developer Mode from the top-left menu bar. 

Once enabled, open Settings (also from the top-left menu bar) and navigate to the Developer Option, where you'll find the Edit Config button. Clicking it will open the claude_desktop_config.json file, allowing you to make the necessary edits. 

OR (if you want to open claude_desktop_config.json from terminal)

#### For macOS:

1. Open your Claude Desktop configuration:

```bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

#### For Windows:

1. Open your Claude Desktop configuration:

```powershell
code %APPDATA%\Claude\claude_desktop_config.json
```

### 2. Add the Exa server configuration:

```json
{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "jordy-exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your-api-key-here",
        "TOOLS": "web_search_exa,get_code_context_exa"
      }
    }
  }
}
```

Replace `your-api-key-here` with your actual Exa API key from [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys).

The `TOOLS` environment variable (or `ENABLED_TOOLS`) is optional. If not specified, only `web_search_exa` and `get_code_context_exa` are enabled by default. Use a comma-separated list to enable specific tools.

### 3. Available Tools & Tool Selection

The Exa MCP server includes powerful tools for developers and researchers:


#### 🌐 **Tools**
- **get_code_context_exa**: Search and get relevant code snippets, examples, and documentation from open source libraries, GitHub repositories, and programming frameworks. Perfect for finding up-to-date code documentation, implementation examples, API usage patterns, and best practices from real codebases.
- **web_search_exa**: Performs real-time web searches with optimized results and content extraction.
- **deep_search_exa**: Deep web search with smart query expansion and high-quality summaries for each result.
- **company_research**: Comprehensive company research tool that crawls company websites to gather detailed information about businesses.
- **crawling**: Extracts content from specific URLs, useful for reading articles, PDFs, or any web page when you have the exact URL.
- **linkedin_search**: Search LinkedIn for companies and people using Exa AI. Simply include company names, person names, or specific LinkedIn URLs in your query.
- **deep_researcher_start**: Start a smart AI researcher for complex questions. The AI will search the web, read many sources, and think deeply about your question to create a detailed research report.
- **deep_researcher_check**: Check if your research is ready and get the results. Use this after starting a research task to see if it's done and get your comprehensive report.

**Note:** By default, only `web_search_exa` and `get_code_context_exa` are enabled. You can enable additional tools using the `TOOLS` or `ENABLED_TOOLS` environment variable (see examples below).

#### 💻 **Setup for Code Search Only** (Recommended for Developers)

```json
{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "jordy-exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your-api-key-here",
        "TOOLS": "get_code_context_exa"
      }
    }
  }
}
```

#### Enable All Tools:

You can either enable all tools or any specific tools. Use a comma-separated list in the `TOOLS` or `ENABLED_TOOLS` environment variable:

```json
{
  "mcpServers": {
    "exa": {
      "command": "npx",
      "args": ["-y", "jordy-exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your-api-key-here",
        "TOOLS": "web_search_exa,get_code_context_exa,crawling_exa,company_research_exa,linkedin_search_exa,deep_researcher_start,deep_researcher_check"
      }
    }
  }
}
```

#### Environment Variables

The server supports the following environment variables:

- **`EXA_API_KEY`** (required): Your Exa API key from [dashboard.exa.ai/api-keys](https://dashboard.exa.ai/api-keys)
- **`TOOLS`** or **`ENABLED_TOOLS`** (optional): Comma-separated list of tool IDs to enable. If not specified, only `web_search_exa` and `get_code_context_exa` are enabled by default.
- **`DEBUG`** (optional): Set to `true` or `1` to enable debug logging

Available tool IDs:
- `web_search_exa`
- `get_code_context_exa`
- `deep_search_exa`
- `crawling_exa`
- `company_research_exa`
- `linkedin_search_exa`
- `deep_researcher_start`
- `deep_researcher_check`

## Using via NPX

If you prefer to run the server directly, you can use npx with environment variables:

```bash
# Run with default tools only (web_search_exa and get_code_context_exa)
EXA_API_KEY=your-api-key-here npx jordy-exa-mcp-server

# Enable specific tools only
EXA_API_KEY=your-api-key-here TOOLS=web_search_exa npx jordy-exa-mcp-server

# Enable multiple tools
EXA_API_KEY=your-api-key-here TOOLS=web_search_exa,get_code_context_exa,crawling_exa npx jordy-exa-mcp-server

# Enable all tools
EXA_API_KEY=your-api-key-here TOOLS=web_search_exa,get_code_context_exa,deep_search_exa,crawling_exa,company_research_exa,linkedin_search_exa,deep_researcher_start,deep_researcher_check npx jordy-exa-mcp-server

# With debug logging enabled
EXA_API_KEY=your-api-key-here TOOLS=web_search_exa DEBUG=true npx jordy-exa-mcp-server
```

---

## Fork Changes

This fork contains the following changes from the original [exa-labs/exa-mcp-server](https://github.com/exa-labs/exa-mcp-server) repository (all changes made after commit `75e902e0b495d94a025f68ab9c79d6e986316cf2`):

### Package Rename and Publishing
- **Package renamed**: Changed from `exa-mcp-server` to `jordy-exa-mcp-server` for npm publishing
- **Version bump**: Updated to version `3.1.4`
- **NPM package**: Published as `jordy-exa-mcp-server` on npm
- Updated all references in `package.json`, `server.json`, `gemini-extension.json`, and documentation

### Build System Migration
- **Migrated from Smithery to Bun**: Replaced Smithery CLI build system with Bun's native build system
- **Build scripts updated**:
  - Removed `@smithery/cli` dependency
  - Changed build command from `smithery build` to `bun build`
  - Updated output directory from `.smithery/stdio/` to `dist/`
  - Removed `smithery.yaml` configuration file
- **Entry point changes**:
  - Modified `src/index.ts` to use `StdioServerTransport` directly instead of Smithery's transport abstraction
  - Added direct stdio transport initialization in the main entry point
  - Changed from default export function to named `createServer` function with separate `main()` entry point
- **Dockerfile updated**: Migrated to use Bun runtime instead of Node.js
  - Changed base image to `oven/bun:1-alpine`
  - Updated build and runtime commands to use `bun` instead of `node`
  - Updated dependency installation to use `bun install`

### Development Tooling
- **Added Beads issue tracking**: Integrated beads (bd) for issue tracking and project management
  - Added `.beads/` directory with configuration files
  - Created `AGENTS.md` with agent instructions and workflow guidelines
  - Added `.beads/.gitignore` for beads-specific files
  - Configured beads metadata and interactions tracking
- **Added `.gitattributes`**: Added Git attributes configuration file

### Documentation Updates
- **README improvements**:
  - Added fork notice at the top
  - Updated all package references from `exa-mcp-server` to `jordy-exa-mcp-server`
  - Enhanced environment variable documentation for tool configuration
  - Updated installation instructions to reflect new package name
  - Clarified tool selection and configuration options

### Code Changes
- **Server initialization refactoring**:
  - Separated server creation logic from transport initialization
  - Added `parseConfig()` function to handle environment variable parsing
  - Added `main()` async function for direct execution
  - Improved error handling and logging
- **Removed Smithery-specific code**: Cleaned up all Smithery CLI dependencies and abstractions

### Files Changed
- **Added**: `.beads/` directory (config, README, metadata, interactions)
- **Added**: `AGENTS.md`, `.gitattributes`, `bun.lock`, `dist/index.js`
- **Modified**: `package.json`, `package-lock.json`, `src/index.ts`, `README.md`, `Dockerfile`, `server.json`, `gemini-extension.json`
- **Removed**: `smithery.yaml`

### Summary Statistics
- **17 files changed**: 653 insertions(+), 70 deletions(-)
- **6 commits** after the base commit

---

Built with ❤️ by team Exa