{"id":28171633,"url":"https://github.com/ahrefs/ahrefs-mcp-server","last_synced_at":"2025-08-02T20:06:47.686Z","repository":{"id":290340282,"uuid":"972357662","full_name":"ahrefs/ahrefs-mcp-server","owner":"ahrefs","description":"Official Ahrefs MCP Server","archived":false,"fork":false,"pushed_at":"2025-05-27T00:20:45.000Z","size":682,"stargazers_count":34,"open_issues_count":3,"forks_count":9,"subscribers_count":24,"default_branch":"main","last_synced_at":"2025-07-22T05:53:45.630Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ahrefs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"zenodo":null}},"created_at":"2025-04-25T00:24:51.000Z","updated_at":"2025-07-17T23:08:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"d9e38604-aeba-4a4a-8ab3-37cc64c8244c","html_url":"https://github.com/ahrefs/ahrefs-mcp-server","commit_stats":null,"previous_names":["ahrefs/ahrefs-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ahrefs/ahrefs-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahrefs%2Fahrefs-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahrefs%2Fahrefs-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahrefs%2Fahrefs-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahrefs%2Fahrefs-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ahrefs","download_url":"https://codeload.github.com/ahrefs/ahrefs-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ahrefs%2Fahrefs-mcp-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268448198,"owners_count":24251997,"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","status":"online","status_checked_at":"2025-08-02T02:00:12.353Z","response_time":74,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-05-15T19:15:35.642Z","updated_at":"2025-08-02T20:06:47.670Z","avatar_url":"https://github.com/ahrefs.png","language":"TypeScript","funding_links":[],"categories":[":globe_with_meridians: MCP Servers"],"sub_categories":[":link: Backlink Analysis"],"readme":"# Ahrefs MCP\nA Model Context Protocol server to connect Claude desktop and other compatible AI assistants to Ahrefs.\n\n## Installation\n`npm` commands need to be executed in a terminal:\n- macOS: open the Terminal from your Applications folder\n- Windows: press Windows + R, type `cmd`, and press Enter\n### Install Node.js and npm\n1. Download Node.js from [nodejs.org](https://nodejs.org/en/download/)\n2. Follow the installation instructions for your operating system\n3. Verify installation by running:\n```sh\nnpm -v\n```\n4. A version number will be printed if installation was successful\n\n#### Windows Users\n- When installing Node.js, use the official installer and make sure the folder is added to PATH when selecting installation options.\n\n### Install Ahrefs MCP Server\n```sh\nnpm install --prefix=~/.global-node-modules @ahrefs/mcp -g\n```\n### Upgrading versions\nIf you've installed our MCP server before, and just want to upgrade, run this command:\n```sh\nnpm install --prefix=~/.global-node-modules @ahrefs/mcp@latest -g\n```\n\n## Configuration\nYou can now add the Ahrefs MCP to your favourite AI assistant app by adding the `ahrefs` part to your app's configuration file:\n```json\n{\n    \"mcpServers\": {\n        \"ahrefs\": {\n            \"command\": \"npx\",\n            \"args\": [\n                \"--prefix=~/.global-node-modules\",\n                \"@ahrefs/mcp\"\n            ],\n            \"env\": {\n                \"API_KEY\": \"YOUR_API_KEY_HERE\"\n            }\n        }\n    }\n}\n```\n\n### Specific for Windows OS\n```json\n{\n    \"mcpServers\": {\n        \"ahrefs\": {\n            \"command\": \"npx\",\n            \"args\": [\n                \"--prefix=C:\\\\Users\\\\YOUR_USERNAME_HERE\\\\.global-node-modules\\\\node_modules\",\n                \"@ahrefs/mcp\"\n            ],\n            \"env\": {\n                \"API_KEY\": \"YOUR_API_KEY_HERE\"\n            }\n        }\n    }\n}\n```\n1. Take note of the double escape backslashes\n2. Take note that the prefix directory is slightly different\n3. Take note of the forward slash for `@ahrefs/mcp`\n4. If you are working with Claude Desktop, run Ctrl-Alt-Del to open Task Manager and kill Claude Desktop. Otherwise, your newly changed config will not be loaded.\n\nTo learn more about creating or controlling API keys, refer to the [official documentation](https://docs.ahrefs.com/docs/api/reference/api-keys-creation-and-management).\n### Where to find the configuration file\n#### Claude Desktop\n1. Download Claude for Desktop\n2. Select `Settings...`\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/claude1.png\" alt=\"Open the Claude menu\"/\u003e\n\u003c/p\u003e\n\n3. Click on `Developer` in the left panel, then `Edit Config`\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/claude2.png\" alt=\"Open the MCP config file\"/\u003e\n\u003c/p\u003e\n\n4. Paste the configuration [above](#configuration) into the open file\n\n5. Restart the Claude app! If the installation is successful, it should look like this:\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/claude3.png\" alt=\"ahrefs MCP appears under 'tools'\"/\u003e\n\u003c/p\u003e\n\nIf you prefer directly navigating to the file, the paths are:\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nIf there are any issues, please refer to the [official documentation](https://modelcontextprotocol.io/quickstart/user)\n#### Cursor\nCursor supports configurations that are either project-specific or global: the MCP configuration file will be at `.cursor/mcp.json` or `~/.cursor/mcp.json` respectively.\nFor more details, read the [official documentation](docs.cursor.com/context/model-context-protocol).\n\n## Common Installation Issues \u0026 Fixes\n\n### 1. Node.js or npm Not Installed / Recognized\n\n**Symptoms:**\n- Running `npm -v` shows an error like `command not found` or `'npm' is not recognized`.\n\n**Fix:**\n- Ensure you've installed Node.js from [nodejs.org](https://nodejs.org/en/download/).\n- Restart your terminal after installation.\n- On **Windows**, make sure the Node.js installer added `npm` to your PATH.\n\n**Platform-Specific Checks:**\n- **Windows:**\n  Open Command Prompt (`Win + R → cmd`) and run:\n  ```\n  node -v\n  npm -v\n  ```\n- **macOS/Linux:**\n  Open Terminal and run:\n  ```\n  which node \u0026\u0026 which npm\n  ```\nIf it returns nothing, Node.js may not be in your `$PATH`.\n\n---\n\n### 2. Permission Errors During Global Installation\n\n**Symptoms:**\n- Errors like `EACCES: permission denied`, especially on macOS or Linux.\n\n**Fix:**\n- Install using a user-scoped global prefix as shown in the installation guide:\n  ```sh\n  npm install --prefix=~/.global-node-modules @ahrefs/mcp -g\n  ```\n- This avoids requiring elevated privileges (`sudo`).\n\n**Extra Tip:**\nIf you used `sudo` previously and created permission issues, reset folder ownership:\n```sh\nsudo chown -R $(whoami) ~/.global-node-modules\n```\n### 2a. macOS Terminal Permissions\n\n**Symptoms:**\n- Terminal shows \"Operation not permitted\" errors\n- Unable to create folders or files\n- Permission denied messages when running npm commands\n\n**Fix:**\nCheck if Terminal has Full Disk Access:\n  - Open System Settings (or System Preferences)\n  - Go to Privacy \u0026 Security → Full Disk Access\n  - Make sure Terminal.app is in the list and checked\n  - If not present, click '+', navigate to Applications → Utilities → Terminal.app\n\n**Note:**\nModern macOS versions require explicit permissions for Terminal access. Without proper permissions, npm installations and other file operations may fail silently or with permission errors.\n\n---\n\n### 3. `npx` Cannot Find the Ahrefs MCP Command\n\n**Symptoms:**\n- Error: `Cannot find package '@ahrefs/mcp'`\n\n**Fix:**\nEnsure your config uses the same prefix used during install:\n```json\n\"command\": \"npx\",\n\"args\": [\n  \"--prefix=~/.global-node-modules\",\n  \"@ahrefs/mcp\"\n]\n```\n\n**Note:**\nDo **not** omit the `--prefix` unless you're installing globally system-wide (not recommended).\n\n---\n\n### 4. Configuration File Not Detected\n\n**Symptoms:**\n- Claude does not list the MCP under “tools”.\n\n**Fix:**\n- Make sure the config file path is correct:\n  - **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n  - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n  - **Linux:** (Rare, but if applicable) `~/.config/Claude/claude_desktop_config.json`\n- Double-check you pasted the configuration **inside the correct section** and restarted Claude after saving.\n\n---\n\n### 5. API Key Problems\n\n**Symptoms:**\n- MCP fails silently or throws an error about `API_KEY`.\n- Claude responds with a message that it ran into authentication issues.\n\n**Fix:**\nEnsure this line is present in the MCP config:\n```json\n\"env\": {\n  \"API_KEY\": \"YOUR_API_KEY_HERE\"\n}\n```\nReplace `YOUR_API_KEY_HERE` with your actual key. Ensure that your API key settings give you the necessary permissions.\n\nFor more help, refer to [Ahrefs API key docs](https://docs.ahrefs.com/docs/api/reference/api-keys-creation-and-management).\n\n---\n\n### 6. Path Expansion Issues\n\n**Symptoms:**\n- Error messages containing `ENOENT` or \"no such file or directory\"\n- npm commands fail with path-related errors\n- `~` or environment variables not being expanded correctly\n\n**Fix:**\nUse absolute paths instead of relying on path expansion:\n\n**Windows:**\n```sh\nC:\\Users\\\u003cusername\u003e\\.global-node-modules\n```\nReplace `\u003cusername\u003e` with your actual Windows username.\n\n**macOS:**\n```sh\n/Users/\u003cusername\u003e/.global-node-modules\n```\nReplace `\u003cusername\u003e` with your macOS username.\n\n**Linux:**\n```sh\n/home/\u003cusername\u003e/.global-node-modules\n```\nReplace `\u003cusername\u003e` with your Linux username.\n\n**Example Configuration:**\n```json\n{\n    \"mcpServers\": {\n        \"ahrefs\": {\n            \"command\": \"npx\",\n            \"args\": [\n                \"--prefix=/Users/username/.global-node-modules\",  // Replace with your absolute path\n                \"@ahrefs/mcp\"\n            ],\n            \"env\": {\n                \"API_KEY\": \"YOUR_API_KEY_HERE\"\n            }\n        }\n    }\n}\n```\n\n**How to Find Your Absolute Path:**\n\n**Windows:**\n1. Open Command Prompt\n2. Type `echo %USERPROFILE%`\n\n**macOS/Linux:**\n1. Open Terminal\n2. Type `echo $HOME`\n\n**Note:**\nUsing absolute paths eliminates issues with path expansion and ensures the configuration works regardless of environment variables or shell configurations.\n\n---\n\n## 🧪 Diagnostic Commands Per Platform\n\n| Issue | Windows Command | macOS/Linux Command |\n|-------|-----------------|---------------------|\n| Check Node version | `node -v \u0026\u0026 npm -v` | `node -v \u0026\u0026 npm -v` |\n| Check if MCP is installed | `npm list -g --prefix=%USERPROFILE%\\.global-node-modules @ahrefs/mcp` | `npm list -g --prefix=~/.global-node-modules @ahrefs/mcp`|\n| Clear corrupted install | Delete folder manually | `rm -rf ~/.global-node-modules` |\n\n---\n\n## 📍 Summary of Key Paths\n\n| Purpose  | Windows | macOS | Linux |\n|----------|---------|-------|-------|\n| Claude config file | `%APPDATA%\\Claude\\claude_desktop_config.json` | `~/Library/Application Support/Claude/claude_desktop_config.json` | `~/.config/Claude/claude_desktop_config.json` (if applicable) |\n| Global MCP install location | `%USERPROFILE%\\.global-node-modules` | `~/.global-node-modules` | `~/.global-node-modules` |\n\n---\n\n## 📘 Still Having Issues?\n\n- Check the [official MCP documentation](https://modelcontextprotocol.io/quickstart/user)\n- Or reach out to internal support at Ahrefs through your usual engineering support channel.\n\nLet us know what errors you're seeing, along with your OS and the output of:\n```sh\nnpm list -g --prefix=~/.global-node-modules @ahrefs/mcp\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahrefs%2Fahrefs-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fahrefs%2Fahrefs-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fahrefs%2Fahrefs-mcp-server/lists"}