# @ahrefs/mcp 中文文档

规范地址：https://npmcn.com/package/%40ahrefs/mcp/

版本：0\.0\.11
npm 元数据更新时间：2025-05-27T00:20:18.606Z
中文译文更新时间：2026-11-08T11:08:36.394Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ahrefs/mcp
原文对照：https://npmcn.com/package/%40ahrefs/mcp/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：519 kB，8 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：2 个
- 首次发布：2025-04-28T08:55:52.383Z
- 最新版本发布：2025-05-27T00:20:18.363Z
- 近 30 天下载量：1795（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 0 个）

## 中文简介

Ahrefs MCP 服务器

## 安装

```sh
npm install @ahrefs/mcp
```

也可以使用：`pnpm add @ahrefs/mcp`、`yarn add @ahrefs/mcp`、`bun add @ahrefs/mcp`

## README

# Ahrefs 磁共振

一个模型背景协议服务器,将克洛德桌面和其他相容的AI助手连接到Ahrefs.

## 安装

`npm` 命令需要在终端中执行 :

-   macOS: 从您的应用程序文件夹打开终端
-   视窗:按视窗+R,类型 `cmd`输入

### 安装节点.js和npm

1.  下载节点.js from [节点js.org](https://nodejs.org/en/download/)
2.  遵循操作系统的安装指令
3.  通过运行验证安装 :

```sh
npm -v
```

4.  如果安装成功, 将会打印一个版本编号

#### 窗口用户

-   在安装Node.js时,使用官方安装器,在选择安装选项时确保文件夹被添加到 PATH.

### 安装 Ahrefs MCP 服务器

```sh
npm install --prefix=~/.global-node-modules @ahrefs/mcp -g
```

### 升级版本

如果您已经安装了我们的 MCP 服务器, 并且只是想升级, 运行此命令 :

```sh
npm install --prefix=~/.global-node-modules @ahrefs/mcp@latest -g
```

## 配置

您现在可以将 Ahrefs MCP 添加到您最喜欢的 AI 助手应用中, 加入 `ahrefs` 应用程序配置文件的一部分 :

```json
{
    "mcpServers": {
        "ahrefs": {
            "command": "npx",
            "args": [
                "--prefix=~/.global-node-modules",
                "@ahrefs/mcp"
            ],
            "env": {
                "API_KEY": "YOUR_API_KEY_HERE"
            }
        }
    }
}
```

### 特定 Windows OS

```json
{
    "mcpServers": {
        "ahrefs": {
            "command": "npx",
            "args": [
                "--prefix=C:\\Users\\YOUR_USERNAME_HERE\\.global-node-modules\\node_modules",
                "@ahrefs/mcp"
            ],
            "env": {
                "API_KEY": "YOUR_API_KEY_HERE"
            }
        }
    }
}
```

1.  注意双回击
2.  注意前缀目录略有不同
3.  注意到前斜线 `@ahrefs/mcp`
4.  如果您与 Claude Desktop 合作, 请运行 Ctrl- Alt- Del 打开任务管理器并杀死 Claude Desktop 。 否则, 您的新更改的配置将不会被载入 .

要更多地了解创建或控制 API 密钥,请参考 [正式文件](https://docs.ahrefs.com/docs/api/reference/api-keys-creation-and-management)。 。 。 .

### 在哪里找到配置文件

#### 克劳德桌面

1.  桌面下载 Claude
2.  选择 `Settings...`

![Open the Claude menu](https://npmcn.com/package/%40ahrefs/mcp/images/claude1.png)

3.  点击 `Developer` 在左面板,然后 `Edit Config`

![Open the MCP config file](https://npmcn.com/package/%40ahrefs/mcp/images/claude2.png)

4.  粘贴配置 [上文](https://npmcn.com/package/%40ahrefs/mcp/#readme-configuration) 输入打开的文件
    
5.  重新启动克洛德的应用程序! 如果安装成功,它应该像这样:
    

![ahrefs MCP appears under 'tools'](https://npmcn.com/package/%40ahrefs/mcp/images/claude3.png)

如果您喜欢直接导航文件, 路径为:

-   马可斯: `~/Library/Application Support/Claude/claude_desktop_config.json`
-   窗口 : `%APPDATA%\Claude\claude_desktop_config.json`

如有问题,请参考 [正式文件](https://modelcontextprotocol.io/quickstart/user)

#### 光标

光标支持针对项目或全局的配置: MCP 配置文件将位于 `.cursor/mcp.json` 或者说 `~/.cursor/mcp.json` 页:1. 详情请改为: [正式文件](https://npmcn.com/package/%40ahrefs/mcp/docs.cursor.com/context/model-context-protocol)。 。 。 .

## 常见安装问题和修复

### 1\. 节点.js或npm 未安装/未识别

**症状:**

-   运行 `npm -v` 显示错误如 `command not found` 或者说 `'npm' is not recognized`。 。 。 .

**修补 :**

-   确保您已经安装了来自 [节点js.org](https://nodejs.org/en/download/)。 。 。 .
-   安装后重新启动终端 .
-   打开 **窗口**,确保添加节点.js安装器 `npm` 去你的路径.

**平台特定检查 :**

-   **窗口 :** 打开命令提示 (E)`Win + R → cmd`)并运行:
    
    ```
    node -v
    npm -v
    ```
    
-   **macOS/ Linux : (中文(简体) )** 打开终端并运行 :
    
    ```
    which node && which npm
    ```
    

如果它不回报,节点。 `$PATH`。 。 。 .

* * *

### 2\. 全球安装过程中的权限出错

**症状:**

-   错误如 `EACCES: permission denied`特别是在MacOS或Linux上.

**修补 :**

-   使用安装指南中显示的用户范围全局前缀安装 :
    
    ```sh
    npm install --prefix=~/.global-node-modules @ahrefs/mcp -g
    ```
    
-   避免要求提高特权(`sudo`) (中文(简体) ).

**额外提示 :** 如果你用过 `sudo` 重置文件夹所有权 :

```sh
sudo chown -R $(whoami) ~/.global-node-modules
```

### 2a. macOS 终端权限

**症状:**

-   终端显示“ 不允许操作” 错误
-   无法创建文件夹或文件
-   运行 npm 命令时权限被拒绝的消息

**修补 :** 检查终端是否有全磁盘访问 :

-   打开系统设置( 或系统首选项)
-   转到隐私和安全 ~ 完整磁盘访问
-   请确定终端。 app 已列在列表并选中
-   如果不存在, 请单击“ +” , 导航到应用程序 → 公用事业 → 终端。 app

**说明:** 现代macOS版本对终端访问需要明确的许可. 没有适当的权限,npm设施和其他文件操作可能静默失败或出现权限错误.

* * *

### 3个. `npx` 无法找到 Ahrefs MCP 命令

**症状:**

-   错误 : `Cannot find package '@ahrefs/mcp'`

**修补 :** 确保您的配置在安装时使用相同的前缀 :

```json
"command": "npx",
"args": [
  "--prefix=~/.global-node-modules",
  "@ahrefs/mcp"
]
```

**说明:** 执行 **没有** 删除 `--prefix` 除非你正在安装全球范围的系统(不推荐).

* * *

### 4\. 未检测到配置文件

**症状:**

-   Claude没有将MCP列在“工具”下.

**修补 :**

-   确保配置文件路径正确 :
    -   **窗口 :** `%APPDATA%\Claude\claude_desktop_config.json`
    -   **马可斯:** `~/Library/Application Support/Claude/claude_desktop_config.json`
    -   **林纳:** (很少,但如果适用) `~/.config/Claude/claude_desktop_config.json`
-   重复检查您粘贴了配置 **在正确的部分** 并在保存后重新启动了克洛德.

* * *

### 5\. API 关键问题

**症状:**

-   MCP 静默失败或投出错误 `API_KEY`。 。 。 .
-   Claude回信说它遇到了认证问题.

**修补 :** 确保此行存在于 MCP 配置中 :

```json
"env": {
  "API_KEY": "YOUR_API_KEY_HERE"
}
```

替换 `YOUR_API_KEY_HERE` 用你真正的钥匙。 确保您的 API 密钥设置给您必要的权限 .

需要更多的帮助,请参见 [Ahrefs API 密钥文件](https://docs.ahrefs.com/docs/api/reference/api-keys-creation-and-management)。 。 。 .

* * *

### 6\. 路径扩展问题

**症状:**

-   含有错误的消息 `ENOENT` 或“没有此类文件或目录”
-   npm 命令因路径出错而失败
-   `~` 或环境变量未正确扩展

**修补 :** 使用绝对路径而不是依赖路径扩展 :

**窗口 :**

```sh
C:\Users\<username>\.global-node-modules
```

替换 `<username>` 与您的 Windows 用户名.

**马可斯:**

```sh
/Users/<username>/.global-node-modules
```

替换 `<username>` 用您的 macOS 用户名 .

**林纳:**

```sh
/home/<username>/.global-node-modules
```

替换 `<username>` 使用您的 Linux 用户名.

**示例配置 :**

```json
{
    "mcpServers": {
        "ahrefs": {
            "command": "npx",
            "args": [
                "--prefix=/Users/username/.global-node-modules",  // Replace with your absolute path
                "@ahrefs/mcp"
            ],
            "env": {
                "API_KEY": "YOUR_API_KEY_HERE"
            }
        }
    }
}
```

**如何找到您的绝对路径 :**

**窗口 :**

1.  打开命令提示
2.  类型 `echo %USERPROFILE%`

**macOS/ Linux : (中文(简体) )**

1.  打开终端
2.  类型 `echo $HOME`

**说明:** 使用绝对路径会用路径扩展来消除问题,并确保配置工作不管环境变量或 shell配置如何.

* * *

## 每个平台的诊断命令

| 问题 | 窗口命令 | macOS/Linux 命令 |
| --- | --- | --- |
| 检查节点版本 | `node -v && npm -v` | `node -v && npm -v` |
| 检查MCP是否安装 | `npm list -g --prefix=%USERPROFILE%\.global-node-modules @ahrefs/mcp` | `npm list -g --prefix=~/.global-node-modules @ahrefs/mcp` |
| 清除已损坏的安装 | 手动删除文件夹 | `rm -rf ~/.global-node-modules` |

* * *

## 关键路径摘要

| 目的 | 窗口 | 马科斯 | 链接 |
| --- | --- | --- | --- |
| Claude 配置文件 | `%APPDATA%\Claude\claude_desktop_config.json` | `~/Library/Application Support/Claude/claude_desktop_config.json` | `~/.config/Claude/claude_desktop_config.json` (如果适用) |
| 全球MCP安装位置 | `%USERPROFILE%\.global-node-modules` | `~/.global-node-modules` | `~/.global-node-modules` |

* * *

## {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}还有问题吗?

-   检查 [mCP正式文件](https://modelcontextprotocol.io/quickstart/user)
-   或者通过你通常的工程支持渠道 联系到Ahrefs的内部支持.

告诉我们你看到什么错误,连同你的操作系统和输出:

```sh
npm list -g --prefix=~/.global-node-modules @ahrefs/mcp
```

## 常见问题

### @ahrefs/mcp 是什么？

Ahrefs MCP 服务器

### 如何安装 @ahrefs/mcp？

在项目目录运行 npm install @ahrefs/mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp，可以用 npx mcp 直接运行。

### @ahrefs/mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ahrefs\_\_mcp 是否存在。

### @ahrefs/mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ahrefs/mcp 可以商用吗？

@ahrefs/mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ahrefs/mcp 的下载量有多少？

根据 npm 官方下载统计，@ahrefs/mcp 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,795 次，日均约 60 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ahrefs/mcp 还在维护吗？

最新版本 0\.0\.11 发布于 2025/05/27（1\.5 年前）；至今共发布 12 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/04/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。