概述与安装

项目简介

exa-mcp-server 是一个基于 Model Context Protocol (MCP) 的服务器，用于将 Exa AI 的实时网页搜索与抓取能力暴露给支持 MCP 协议的客户端（如 Claude Desktop、Claude Code、Cursor 等）。该服务器封装了 Exa 的搜索 API，提供一组可配置的工具集，使大语言模型能够获取最新的网页内容。

服务器的核心特征包括：

• 多传输支持：同时支持 stdio（本地）和 HTTP/SSE（远程）两种传输方式 资料来源：README.md package.json
• 可配置工具集：通过 tools 参数按需启用或禁用具体工具，默认为精简集合 资料来源：src/mcp-handler.ts
• 托管远程实例：官方提供远程 MCP 端点 https://mcp.exa.ai/mcp，用户无需本地部署即可使用 资料来源：npm.readme.md

架构概览

服务器采用模块化架构，核心入口为 src/mcp-handler.ts，负责工具注册、请求路由与配置解析。每个 Exa 功能（如网页搜索、高级搜索、深度搜索、内容抓取）作为独立的工具模块实现，统一通过 MCP 协议暴露。

flowchart LR
    A[MCP 客户端<br/>Claude/Cursor] -->|stdio / SSE| B(exa-mcp-server)
    B --> C{工具注册表<br/>availableTools}
    C --> D[web_search_exa]
    C --> E[web_fetch_exa]
    C --> F[web_search_advanced_exa]
    C --> G[deep_search_exa]
    D --> H[Exa Search API]
    E --> H
    F --> H
    G --> H

工具的启用状态由 src/mcp-handler.ts 中定义的 availableTools 对象控制；其中 web_search_exa 与 web_fetch_exa 默认启用，其余工具（包括已弃用的 company_research_exa、people_search_exa 等）默认禁用，需通过 URL 参数显式开启。资料来源：src/mcp-handler.ts

安装方式

方式一：使用托管远程 MCP（推荐）

最简便的方式是直接连接官方托管的远程 MCP 服务器。该方式无需配置 API Key，使用服务器内置的回退密钥。资料来源：npm.readme.md

{
  "mcpServers": {
    "exa": {
      "url": "https://mcp.exa.ai/mcp"
    }
  }
}

若需启用高级工具集，可在 URL 中通过 tools 查询参数指定：

https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa

方式二：通过 npm 安装（本地 stdio）

本地安装适合需要自托管、自定义 API Key 或离线运行的场景。资料来源：package.json

npx exa-mcp-server

Claude Desktop 的 claude_desktop_config.json 配置示例：

{
  "mcpServers": {
    "exa-mcp-server": {
      "command": "npx",
      "args": ["-y", "exa-mcp-server"],
      "env": {
        "EXA_API_KEY": "your_api_key"
      }
    }
  }
}

社区提示：社区曾报告通过 Smithery 打包后的 .smithery/index.cjs 文件因构建流程注入了多余的 shebang 行而导致 stdio 传输失败（Issue #65）。如通过非官方打包渠道安装遇到启动错误，可检查构建产物中的 shebang 行。资料来源：Issue #65

配置与工具选择

服务器通过环境变量与 URL 参数两层机制完成配置。配置文件 api/well-known-mcp-config.ts 暴露了 JSON Schema，描述了可用的配置项：

资料来源：api/well-known-mcp-config.ts

工具清单

根据 src/mcp-handler.ts 中的注册表，服务器共提供以下工具：

资料来源：src/mcp-handler.ts README.md

社区提示：在 3.x 版本之后，工具选择方式由显式列表切换为基于 ?tools= URL 参数的形式（Issue #48）。从旧版本升级时需注意配置格式变化。资料来源：Issue #48

远程端点提示

社区反馈显示远程端点 https://mcp.exa.ai/mcp 在使用标准 SSE GET 连接时可能返回 405 Method Not Allowed（Issue #86），部分客户端（如 Claude Code）通过 POST 建立会话不受影响；此外该端点历史上曾出现临时不可用的情况（Issue #108）。如遇连接异常，可临时切换到本地 stdio 部署作为回退方案。资料来源：Issue #86 Issue #108

安全提示

根据社区提交的安全扫描结果（Issue #359），MCTS 扫描器在仓库中识别到若干高危发现（包括 exec() 调用与潜在注入面），整体评分为 5/100；另有 Regulatory Signals 颁发的 Silver 等级认证（Issue #361）。在生产环境部署本地实例时，建议：

• 隔离运行时环境（容器或专用用户）
• 审计环境变量中的 API Key 来源
• 关注官方仓库的安全公告与版本更新

资料来源：Issue #359 Issue #361

参见

• 工具参考：可用工具与参数详解
• 高级搜索与类别过滤
• 远程 MCP 与部署模式

架构概览

exa-mcp-server 是一个基于 Model Context Protocol（MCP） 的服务器实现，将 Exa 搜索 API 封装为 LLM 客户端可调用的工具集合。其整体架构围绕「传输层 → 工具注册中心 → Exa API 适配」三层模型展开。包入口通过 package.json 中的 bin 字段声明为 dist/stdio.cjs，并通过 esbuild 打包为单一 CJS 可执行文件以适配 stdio 传输。资料来源：package.json:1-15。

服务器名称 (mcpName) 注册为 io.github.exa-labs/exa-mcp-server，便于 MCP 客户端进行命名空间识别。资料来源：package.json:1-15。

传输机制

项目同时支持两种传输模式：

1. 本地 stdio 传输 — 适用于 Claude Desktop、Claude Code 等本地 MCP 客户端，通过 claude mcp add 命令注册。构建脚本使用 --format=cjs 并附加 Node shebang，确保产物可直接执行。资料来源：package.json:1-15。
2. 远程 HTTP/SSE 传输 — 托管端点为 https://mcp.exa.ai/mcp，无需本地安装或 API Key 即可使用。URL 查询参数支持 exaApiKey 与 tools 注入。资料来源：README.md。

社区反馈显示，远程端点在标准 SSE GET 请求下曾返回 405 Method Not Allowed（参见 Issue #86），仅有部分客户端（如 Claude Code 使用 POST）能成功连接；同时 Issue #108 报告了端点偶发不可用的情况。Issue #65 还指出 npm 发布后 .smithery/index.cjs 中出现多 shebang 行的问题，会破坏 stdio 传输。资料来源：社区问题追踪 #86、#65、#108。

构建命令 build:stdio 使用 esbuild 将 src/stdio-cli.ts 打包为单一 CJS 文件，目标是 Node 20 平台，输出文件为 dist/stdio.cjs，并通过 chmod +x 赋予可执行权限。资料来源：package.json:1-15。

工具注册中心

src/mcp-handler.ts 是核心调度模块，定义了 availableTools 注册表，声明每个工具的 name、description 与默认 enabled 状态。默认启用 web_search_exa 与 web_fetch_exa 两个工具；web_search_advanced_exa、各类已弃用工具（如 company_research_exa、linkedin_search_exa 等）默认禁用，需通过 tools 参数显式启用。资料来源：src/mcp-handler.ts:1-30。

每个工具通过独立的 registerXxxTool 函数注入，工具实现位于 src/tools/ 目录，例如 webSearch.ts、deepSearch.ts。deepSearch 工具支持 deep（4-12 秒）与 deep-reasoning（12-50 秒）两种深度模式，并提供结构化 JSON 输出（outputSchema、structuredOutput）。资料来源：src/tools/deepSearch.ts:1-15。

webSearch 工具通过正则从 query 中提取 category:<type> 前缀来限定结果类别（company、research paper、news、personal site、people），而无需调用方额外传参。资料来源：src/tools/webSearch.ts:1-20。

数据模型与配置发现

src/types.ts 定义了完整的 Exa API 类型契约，包括 ExaSearchRequest（含 category、includeDomains、contents 等字段）和 ExaSearchResponse（含 results、costDollars、statuses 等）。contents 子对象支持 text、context、summary、highlights、livecrawl、subpages 等内容提取选项。资料来源：src/types.ts:1-20。

远程端点通过 /.well-known/mcp-config 提供 JSON Schema 配置自描述，允许 MCP 客户端自动发现可用参数。Schema 中 tools 字段为逗号分隔字符串，x-available-values 列出了 web_search_exa、web_search_advanced_exa、web_fetch_exa 三个候选值，并附带 examples 提示典型组合。资料来源：api/well-known-mcp-config.ts:1-30。

flowchart LR
    Client["MCP 客户端"] -->|stdio / HTTP+SSE| Transport["传输层<br/>stdio.cjs / mcp.exa.ai"]
    Transport --> Handler["mcp-handler.ts<br/>工具注册中心"]
    Handler -->|register*Tool| Tools["src/tools/*<br/>webSearch / deepSearch / webFetch ..."]
    Tools -->|HTTPS| ExaAPI["Exa Search API"]
    Tools --> Response["ExaSearchResponse<br/>results / costDollars"]
    Response --> Client

配置与部署

部署方式有两种典型路径：

• 本地模式：通过 npx exa-mcp-server 启动 stdio 服务器，环境变量 EXA_API_KEY 注入凭据。Issue #48 反馈曾在版本更新后导致 tools 选择配置失效，提示用户在升级后需复核 MCP 配置。资料来源：社区问题追踪 #48。
• 远程模式：直接连接 https://mcp.exa.ai/mcp，通过 URL 参数选择工具集，例如 ?tools=web_search_exa,web_search_advanced_exa,web_fetch_exa。该模式由 Exa 官方托管，无需用户管理 API Key。资料来源：README.md。

无论哪种模式，工具调用最终都通过 Zod schema 校验后映射为 Exa REST 请求，错误统一由 utils/errorHandler.ts 格式化后返回 MCP 错误响应，从而在传输层与业务层之间形成清晰的关注点分离。

See Also

• 工具参考 — 各工具的完整参数与返回值说明
• Exa API 类型契约 — ExaSearchRequest / ExaSearchResponse 详解
• 部署与安全审计 — MCTS 与 Regulatory Signals 审计发现汇总

概述

exa-mcp-server 是一个基于 Model Context Protocol (MCP) 的服务器，封装了 Exa AI 的搜索与抓取能力，对外暴露一组可配置的工具集（tools）。根据 package.json 中的描述，服务器"提供实时网络搜索并支持可配置的工具选择，允许用户启用或禁用特定的搜索能力"。这意味着工具的启用与否、参数行为、以及提示（prompts）均可通过配置或 URL 参数控制，而无需修改源码。

整个工具注册流程由 src/mcp-handler.ts 中的 availableTools 字典统一管理；该字典是所有工具元数据（name、description、enabled 标志）的"事实来源"。

可用工具清单

下表汇总了当前仓库中实现或引用的全部工具，状态来自 src/mcp-handler.ts 中的 availableTools 字典：

部署为远程 MCP 时，可在 URL 中追加 tools=... 启用非默认工具。例如 https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa 即可同时启用三款工具（资料来源：README.md）。

工具注册与执行架构

src/mcp-handler.ts 是核心注册中心。下图展示了从 MCP 客户端请求到具体工具实现的调用链：

flowchart LR
    A[MCP Client] --> B[mcp-handler.ts<br/>availableTools 字典]
    B --> C{enabled?}
    C -- yes --> D[registerWebSearchTool]
    C -- yes --> E[registerWebFetchTool]
    C -- yes --> F[registerWebSearchAdvancedTool]
    C -- yes --> G[registerDeepSearchTool]
    D --> H[Exa API]
    E --> H
    F --> H
    G --> H
    H --> I[ExaSearchResponse<br/>src/types.ts]
    I --> A

每个 register* 函数通过 McpServer.tool(name, description, schema, handler) 将工具挂载到服务器，并附带 readOnlyHint / destructiveHint / openWorldHint / idempotentHint 等 MCP 注解（资料来源：src/tools/webSearch.ts）。mcp-handler.ts 还会在初始化时调用 trackMCP 集成 Agnost 埋点，用于远程模式下的使用统计；若初始化失败，错误会被捕获而不会中断启动。

配置选项

配置通过三类入口暴露：stdio 启动参数、URL query 参数，以及 /.well-known/mcp-config 端点。

api/well-known-mcp-config.ts 暴露的 JSON Schema 定义了三个字段：exaApiKey（Exa API 密钥，未提供时服务器使用兜底密钥）、tools（以逗号分隔启用的工具标识符，合法值由 x-available-values 约束为 web_search_exa、web_search_advanced_exa、web_fetch_exa）以及 debug（布尔值，开启调试日志）。

工具自身参数以 Zod schema 形式定义于各自的文件中。例如 src/tools/webSearch.ts 仅接受 query 与 numResults 两个参数；src/tools/deepSearch.ts 进一步支持 type（deep / deep-reasoning）、outputSchema、systemPrompt、structuredOutput 等高级参数，并显式说明 'deep' 模式耗时 4–12 秒、'deep-reasoning' 模式 12–50 秒。类型层统一在 src/types.ts 中以 ExaSearchRequest、ExaSearchResponse 等接口表达，便于扩展与维护。

常见问题与社区反馈

工具配置变更与工具可用性是社区中最高频的议题。Issue #48《Selecting tools after new release》指出，新版本发布后，用户在 MCP 配置中显式指定启用工具的方式发生了变化，需要重新配置才能恢复预期工具集（资料来源：Issue #48）。针对该问题，最新的解决方式即通过 ?tools= query 参数或在 stdio 配置中显式列出期望启用的工具（资料来源：README.md）。

此外，Issue #65 报告了 .smithery/index.cjs 在构建过程中出现多 shebang 行导致 stdio 传输失败的问题，间接说明工具分发管线的健壮性也是关注点（资料来源：Issue #65）。部署侧，Issue #86 反馈远程 SSE 端点对标准 GET 请求返回 405，提示在使用 https://mcp.exa.ai/mcp 时应优先采用 POST 初始化并按 MCP 规范使用流式传输（资料来源：Issue #86）。这些反馈共同表明，工具参考与配置既涉及客户端配置语法，也涉及传输与分发链路。

See Also

• README.md
• src/mcp-handler.ts
• api/well-known-mcp-config.ts
• src/types.ts
• package.json

运维、安全与故障排查

本页面向运维与安全工程师，介绍 exa-mcp-server 在部署、运行监控与故障排查方面的关键事项，并结合社区反馈的高频问题提供处理思路。

项目形态与构建产物

服务器以 Node.js 包形式发布，核心入口位于 package.json 中声明：

• module: "./src/stdio.ts" — ESM 模式主入口
• bin: { "exa-mcp-server": "dist/stdio.cjs" } — 构建后产出的可执行 CLI
• build:stdio 脚本使用 esbuild 将 src/stdio-cli.ts 打包为 CJS，并通过 --banner:js="#!/usr/bin/env node" 注入 shebang

资料来源：package.json:1-30

社区问题 #65 报告：npm 包内 .smithery/index.cjs 出现多行 shebang 导致 stdio 传输失败。解决方法通常是清理构建产物并避免多次注入 shebang 横幅。

工具注册与最小权限控制

服务器采用注册表模式管理可暴露给客户端的工具集合。src/mcp-handler.ts 中的 availableTools 对象集中声明了所有工具及其默认启用状态：

通过远程托管端点 https://mcp.exa.ai/mcp?tools=... 的查询参数可动态启用工具，例如：

https://mcp.exa.ai/mcp?exaApiKey=YOUR_KEY&tools=web_search_exa,web_search_advanced_exa,web_fetch_exa

资料来源：src/mcp-handler.ts:1-40、README.md:1-60、npm.readme.md:1-40

flowchart LR
    A[MCP Client] -->|tools=query| B[Remote MCP<br/>mcp.exa.ai/mcp]
    B --> C{API Key<br/>校验}
    C -->|通过| D[availableTools<br/>注册表]
    D --> E[web_search_exa]
    D --> F[web_search_advanced_exa]
    D --> G[web_fetch_exa]

安全态势与社区审计

exa-mcp-server 已进入 MCP Trust Registry，获评 Silver 等级（评分 79）。另一方面，社区使用 MCTS（Model Context Threat Scanner）对仓库进行了 105 项分析器扫描，共发现 7 项 HIGH/CRITICAL 级别问题，主要包括：

1. 代码中调用 exec() 类的进程执行能力，存在命令注入面；
2. 输入参数未充分净化，可能触发注入；
3. 构建/发布生命周期脚本被标记为可疑。

建议运维方在自托管场景下：(1) 限定容器化部署并以非 root 用户运行；(2) 关闭不需要的弃用工具；(3) 通过反向代理对入站 JSON-RPC 请求做速率限制与审计。

资料来源：README.md:1-30、package.json:1-30（社区上下文：issues #359、#361）

常见故障与排查

1. stdio 传输无法启动

症状：Claude Code 或其他 MCP 客户端报告无法建立连接。常见原因与对策：

• 构建后 dist/stdio.cjs 缺少可执行权限 → 运行 chmod +x dist/stdio.cjs（已在 package.json 的 build:stdio 脚本中处理）
• .smithery/index.cjs 出现重复 shebang → 清理构建缓存后重新打包

资料来源：package.json:1-30

2. 远程端点返回 405 Method Not Allowed

社区问题 #86 报告：通用 MCP 客户端使用 HTTP GET 方式建立 SSE 连接时被 https://mcp.exa.ai/mcp 拒绝。该远程端点对握手方法存在限制，仅特定客户端（如 Claude Code 使用 POST）能正常连通。建议：

• 在客户端配置中确认使用受支持的传输方式；
• 自托管时直接使用 stdio 或官方文档列出的传输协议。

资料来源：README.md:1-60（社区上下文：issue #86、#108）

3. 工具选择回归

社区问题 #48 指出，新版本发布后通过配置选择可用工具的行为发生变化。可通过 api/well-known-mcp-config.ts 中声明的 JSON Schema 字段 tools 进行精确控制，例如 tools=web_search_exa,web_search_advanced_exa。

资料来源：api/well-known-mcp-config.ts:1-30

4. 提示与参数校验

社区问题 #358 报告：prompts/get 在零参数提示 web_search_help 上拒绝省略 arguments 字段。该问题源于 JSON-RPC 校验层在严格模式下不接受空对象，需在客户端显式传 arguments: {}。

资料来源：src/types.ts:1-60

5. 调试模式

通过 URL 查询参数 debug=true 启用调试日志，便于追踪请求 ID 与工具调用链路。src/tools/webSearch.ts 中实现了基于 createRequestLogger 的请求级日志封装：

const requestId = `${toolId}-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;
const logger = createRequestLogger(requestId, toolId);

资料来源：src/tools/webSearch.ts:1-40、api/well-known-mcp-config.ts:1-30

进阶搜索的安全使用

src/tools/deepSearch.ts 暴露 type: "deep" | "deep-reasoning" 两种模式，分别耗时 4–12 秒与 12–50 秒。运维建议：

• 对 outputSchema 与 systemPrompt 实施长度上限校验（已内置 z.string().max(32000)）；
• 限制 additionalQueries 数量，避免被滥用为代理放大器。

资料来源：src/tools/deepSearch.ts:1-40

See Also

• README.md — 工具列表与远程接入指引
• src/mcp-handler.ts — 工具注册表与启用策略
• api/well-known-mcp-config.ts — 远程配置 Schema

Pitfall Log / 踩坑日志

项目：exa-labs/exa-mcp-server

摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/exa-labs/exa-mcp-server | host_targets=mcp_host, claude_code, claude, cursor, gemini_cli

2. 配置坑 · 来源证据：prompts/get rejects omitted optional arguments for zero-argument prompt web_search_help

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：prompts/get rejects omitted optional arguments for zero-argument prompt web_search_help
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/exa-labs/exa-mcp-server/issues/358 | 来源类型 github_issue 暴露的待验证使用条件。

3. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/exa-labs/exa-mcp-server | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/exa-labs/exa-mcp-server | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/exa-labs/exa-mcp-server | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/exa-labs/exa-mcp-server | no_demo; severity=medium

7. 安全/权限坑 · 来源证据：MCTS Security Scan: 7 HIGH/CRITICAL findings — exec() call, injection surfaces, suspicious lifecycle script

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCTS Security Scan: 7 HIGH/CRITICAL findings — exec() call, injection surfaces, suspicious lifecycle script
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/exa-labs/exa-mcp-server/issues/359 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

8. 安全/权限坑 · 来源证据：[Regulatory Signals] exa-mcp-server is listed on the MCP Trust Registry — claim it

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Regulatory Signals] exa-mcp-server is listed on the MCP Trust Registry — claim it
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/exa-labs/exa-mcp-server/issues/361 | 来源类型 github_issue 暴露的待验证使用条件。

9. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/exa-labs/exa-mcp-server | issue_or_pr_quality=unknown

10. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/exa-labs/exa-mcp-server | release_recency=unknown