{"_id":"@ahrefs/mcp","_rev":"17-8859842df9f159510e7f450a5d263af9","name":"@ahrefs/mcp","dist-tags":{"latest":"0.0.11"},"versions":{"0.0.5":{"name":"@ahrefs/mcp","version":"0.0.5","keywords":["mcp","model-context-protocol","openapi","ahrefs"],"author":{"name":"Ahrefs"},"license":"MIT","_id":"@ahrefs/mcp@0.0.5","maintainers":[{"name":"khady","email":"louis@louisroche.net"},{"name":"rustykey","email":"iam@stfoo.ru"},{"name":"germes","email":"e.chemohonenko@gmail.com"},{"name":"bryanthomaschen","email":"bryanthomaschen@gmail.com"},{"name":"denstr","email":"strelkov.d.d@gmail.com"},{"name":"jchavarri","email":"javier.chavarri@gmail.com"},{"name":"zindel","email":"alexei.golovko@gmail.com"},{"name":"feihong","email":"feihong.hsu@gmail.com"},{"name":"jkvt2","email":"vince.tan@ahrefs.com"}],"bin":{"mcp":"build/index.js"},"dist":{"shasum":"9f20fe421424f4b8d4ac45ac7b4069b15f9c3724","tarball":"https://registry.npmjs.org/@ahrefs/mcp/-/mcp-0.0.5.tgz","fileCount":7,"integrity":"sha512-+QS+4CyqGRXXMTCvOg7RkzAQVRVQtDzR/pmbspzdewU3a63a54/nCDuH+gFCm0gsvwFIgiPGnqInlOCrxe+AlQ==","signatures":[{"sig":"MEQCIA48Tmk0+8ezBgbHgDb6mxpEkaA+LjwOIJDtyGTbzOYbAiB2pk/CizWpLGiYjJIj33pAfOq3/Tl5KTzAv8yRMtDl3g==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":483643},"main":"build/index.js","type":"module","gitHead":"4c3a0ab57d76a2ad95e5786382a4979e4bf64e8c","scripts":{"build":"tsc","start":"npm run build && node build/index.js"},"_npmUser":{"name":"jkvt2","email":"vince.tan@ahrefs.com"},"_npmVersion":"10.9.2","description":"Ahrefs MCP server","directories":{},"_nodeVersion":"23.11.0","dependencies":{"axios":"^1.8.0","@modelcontextprotocol/sdk":"^1.8.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.0.5_1745830552498_0.9981667722992613","host":"s3://npm-registry-packages-npm-production"}},"0.0.6":{"name":"@ahrefs/mcp","version":"0.0.6","keywords":["mcp","model-context-protocol","openapi","ahrefs"],"author":{"name":"Ahrefs"},"license":"MIT","_id":"@ahrefs/mcp@0.0.6","maintainers":[{"name":"khady","email":"louis@louisroche.net"},{"name":"rustykey","email":"iam@stfoo.ru"},{"name":"germes","email":"e.chemohonenko@gmail.com"},{"name":"bryanthomaschen","email":"bryanthomaschen@gmail.com"},{"name":"denstr","email":"strelkov.d.d@gmail.com"},{"name":"jchavarri","email":"javier.chavarri@gmail.com"},{"name":"zindel","email":"alexei.golovko@gmail.com"},{"name":"feihong","email":"feihong.hsu@gmail.com"},{"name":"jkvt2","email":"vince.tan@ahrefs.com"}],"bin":{"mcp":"build/index.js"},"dist":{"shasum":"a43010ff6cc8729fc996646a6839871ae9ca3d2c","tarball":"https://registry.npmjs.org/@ahrefs/mcp/-/mcp-0.0.6.tgz","fileCount":8,"integrity":"sha512-JFSqcP5ykREync6BJQT4jCiLXejmkFS8oSnGRrnpfKAK139W+z0fBvnX4ditsJO7bppopcVnfzaef6z0OJ2a1g==","signatures":[{"sig":"MEQCIDKkL+mIExzDzvCAu0g6Zdnd0tvgNeq8QRNa3mVsT/G5AiBKrUkfF0ABon7BAquTCDEkXEVHTD+yuNDmQarqTg64LQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":485336},"main":"build/index.js","type":"module","gitHead":"7db451ec4037d94afd8629d591cbcb6367af6ad0","scripts":{"build":"tsc","start":"npm run build && node build/index.js"},"_npmUser":{"name":"jkvt2","email":"vince.tan@ahrefs.com"},"_npmVersion":"10.9.2","description":"Ahrefs MCP server","directories":{},"_nodeVersion":"23.11.0","dependencies":{"axios":"^1.8.0","@modelcontextprotocol/sdk":"^1.8.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.0.6_1746079946652_0.2898740972628959","host":"s3://npm-registry-packages-npm-production"}},"0.0.7":{"name":"@ahrefs/mcp","version":"0.0.7","keywords":["mcp","model-context-protocol","openapi","ahrefs"],"author":{"name":"Ahrefs"},"license":"MIT","_id":"@ahrefs/mcp@0.0.7","maintainers":[{"name":"khady","email":"louis@louisroche.net"},{"name":"rustykey","email":"iam@stfoo.ru"},{"name":"germes","email":"e.chemohonenko@gmail.com"},{"name":"bryanthomaschen","email":"bryanthomaschen@gmail.com"},{"name":"denstr","email":"strelkov.d.d@gmail.com"},{"name":"jchavarri","email":"javier.chavarri@gmail.com"},{"name":"zindel","email":"alexei.golovko@gmail.com"},{"name":"feihong","email":"feihong.hsu@gmail.com"},{"name":"jkvt2","email":"vince.tan@ahrefs.com"}],"bin":{"mcp":"build/index.js"},"dist":{"shasum":"9af246e11be9cebaded359a32aa627b9ac67d6f7","tarball":"https://registry.npmjs.org/@ahrefs/mcp/-/mcp-0.0.7.tgz","fileCount":8,"integrity":"sha512-kxCW3hdd/Rrm8vFqtNvkAe4TVNnxThzCV2FpP2F/MRiTU+aqtsGWfFDQrKJSpQrv9hYjKxw0lSh9ZUeB+NdjPQ==","signatures":[{"sig":"MEYCIQDdFJoo5c4Fp0QozxOk0V2JGTebatxBQgJDTj96tjbtowIhAKY4KpwuQTeE7LUT+mfNCAcf39g8zLAksIvLUoK0WAvf","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":495647},"main":"build/index.js","type":"module","gitHead":"896f28ecab3fbc652f45bc9f157b311bf216f36b","scripts":{"build":"tsc","start":"npm run build && node build/index.js"},"_npmUser":{"name":"jkvt2","email":"vince.tan@ahrefs.com"},"_npmVersion":"10.9.2","description":"Ahrefs MCP server","directories":{},"_nodeVersion":"23.11.0","dependencies":{"axios":"^1.8.0","@modelcontextprotocol/sdk":"^1.8.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.0.7_1746497543861_0.06340534355708405","host":"s3://npm-registry-packages-npm-production"}},"0.0.8":{"name":"@ahrefs/mcp","version":"0.0.8","keywords":["mcp","model-context-protocol","openapi","ahrefs"],"author":{"name":"Ahrefs"},"license":"MIT","_id":"@ahrefs/mcp@0.0.8","maintainers":[{"name":"khady","email":"louis@louisroche.net"},{"name":"rustykey","email":"iam@stfoo.ru"},{"name":"germes","email":"e.chemohonenko@gmail.com"},{"name":"bryanthomaschen","email":"bryanthomaschen@gmail.com"},{"name":"denstr","email":"strelkov.d.d@gmail.com"},{"name":"jchavarri","email":"javier.chavarri@gmail.com"},{"name":"zindel","email":"alexei.golovko@gmail.com"},{"name":"feihong","email":"feihong.hsu@gmail.com"},{"name":"jkvt2","email":"vince.tan@ahrefs.com"}],"bin":{"mcp":"build/index.js"},"dist":{"shasum":"7a6a29e60132609a9e6f495e2b21ddeb03f10271","tarball":"https://registry.npmjs.org/@ahrefs/mcp/-/mcp-0.0.8.tgz","fileCount":8,"integrity":"sha512-kO4ohLlxHIgzRHpCUPLF/CHjBnHn86IE6XVwwZcvqT6je/O5ZguUSx7FbfKJdKRhdcTm/tEFioVmE/HKvz67FQ==","signatures":[{"sig":"MEYCIQCVhgycTFJCdxhpzhCKVOWU4nKSyeWdBGrmR4nOb3C9OwIhALIPUkWosg4TlOZ8PTSsBvB3lCKnl0kiE/T2g4EqerkH","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":507677},"main":"build/index.js","type":"module","gitHead":"d864edcd0bc2d33c712b6ef734e68f8b350ddc65","scripts":{"build":"tsc","start":"npm run build && node build/index.js"},"_npmUser":{"name":"jkvt2","email":"vince.tan@ahrefs.com"},"_npmVersion":"10.9.2","description":"Ahrefs MCP server","directories":{},"_nodeVersion":"23.11.0","dependencies":{"axios":"^1.8.0","@modelcontextprotocol/sdk":"^1.8.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.0.8_1746697995514_0.43529904248931306","host":"s3://npm-registry-packages-npm-production"}},"0.0.9":{"name":"@ahrefs/mcp","version":"0.0.9","keywords":["mcp","model-context-protocol","openapi","ahrefs"],"author":{"name":"Ahrefs"},"license":"MIT","_id":"@ahrefs/mcp@0.0.9","maintainers":[{"name":"khady","email":"louis@louisroche.net"},{"name":"rustykey","email":"iam@stfoo.ru"},{"name":"germes","email":"e.chemohonenko@gmail.com"},{"name":"bryanthomaschen","email":"bryanthomaschen@gmail.com"},{"name":"denstr","email":"strelkov.d.d@gmail.com"},{"name":"jchavarri","email":"javier.chavarri@gmail.com"},{"name":"zindel","email":"alexei.golovko@gmail.com"},{"name":"feihong","email":"feihong.hsu@gmail.com"},{"name":"jkvt2","email":"vince.tan@ahrefs.com"}],"bin":{"mcp":"build/index.js"},"dist":{"shasum":"8647515fed812666d640798ede3a5fa5a640ad35","tarball":"https://registry.npmjs.org/@ahrefs/mcp/-/mcp-0.0.9.tgz","fileCount":8,"integrity":"sha512-Zl5WLfj5fhMrlP9XNjqAzrg5ECJcm/t/tTgUiFCw4fI40Bvb1VZyFVt7CN28aaJg2mUIAswOWeuDWc/hiqwYBg==","signatures":[{"sig":"MEUCIQCdkm51P9vF64rgLffH+9W4YEpMHtmG79Bm1+sixhl18gIgMY9vx3+5YnMDFOyl+kksTCeXy8hburzszUvTPoPW+GA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":513577},"main":"build/index.js","type":"module","gitHead":"d43b7fcd3034c361339b203adc63f31de1ab492b","scripts":{"build":"tsc","start":"npm run build && node build/index.js"},"_npmUser":{"name":"jkvt2","email":"vince.tan@ahrefs.com"},"_npmVersion":"10.9.2","description":"Ahrefs MCP server","directories":{},"_nodeVersion":"23.11.0","dependencies":{"axios":"^1.8.0","@modelcontextprotocol/sdk":"^1.8.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.0.9_1747102258293_0.13840774256419075","host":"s3://npm-registry-packages-npm-production"}},"0.0.10":{"name":"@ahrefs/mcp","version":"0.0.10","keywords":["mcp","model-context-protocol","openapi","ahrefs"],"author":{"name":"Ahrefs"},"license":"MIT","_id":"@ahrefs/mcp@0.0.10","maintainers":[{"name":"khady","email":"louis@louisroche.net"},{"name":"rustykey","email":"iam@stfoo.ru"},{"name":"germes","email":"e.chemohonenko@gmail.com"},{"name":"bryanthomaschen","email":"bryanthomaschen@gmail.com"},{"name":"denstr","email":"strelkov.d.d@gmail.com"},{"name":"jchavarri","email":"javier.chavarri@gmail.com"},{"name":"zindel","email":"alexei.golovko@gmail.com"},{"name":"feihong","email":"feihong.hsu@gmail.com"},{"name":"jkvt2","email":"vince.tan@ahrefs.com"}],"bin":{"mcp":"build/index.js"},"dist":{"shasum":"0151eb9be2cb34f090e5d780ba9b25cf9b2749c8","tarball":"https://registry.npmjs.org/@ahrefs/mcp/-/mcp-0.0.10.tgz","fileCount":8,"integrity":"sha512-hc6o7Q7TZ3I0ouBLFEdiQ0owIhQS2K7kqkGhUucwxxEhs1PpK2wuyhAUamNRpCj/L6ectyW6Eu/47nYVBYP6Lw==","signatures":[{"sig":"MEYCIQC/BwM0m10sWmMuCA8SqCcrgVlnjqN5riAtGx8V8n/F/QIhAKKvMU67hzMt92d/6ybgjzLD3+UCm7jHd0VmkL+bDse+","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":512482},"main":"build/index.js","type":"module","gitHead":"883985792c86ade89cbc1112f9194ba830c795d3","scripts":{"build":"tsc","start":"npm run build && node build/index.js"},"_npmUser":{"name":"jkvt2","email":"vince.tan@ahrefs.com"},"_npmVersion":"10.9.2","description":"Ahrefs MCP server","directories":{},"_nodeVersion":"23.11.0","dependencies":{"axios":"^1.8.0","@modelcontextprotocol/sdk":"^1.8.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"^22.13.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.0.10_1747275347165_0.12599925129492906","host":"s3://npm-registry-packages-npm-production"}},"0.0.11":{"name":"@ahrefs/mcp","version":"0.0.11","description":"Ahrefs MCP server","main":"build/index.js","type":"module","scripts":{"build":"tsc","start":"npm run build && node build/index.js"},"keywords":["mcp","model-context-protocol","openapi","ahrefs"],"bin":{"mcp":"build/index.js"},"author":{"name":"Ahrefs"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.8.0","axios":"^1.8.0"},"devDependencies":{"@types/node":"^22.13.0","typescript":"^5.7.0"},"_id":"@ahrefs/mcp@0.0.11","gitHead":"c55e838c66741f4d6b5226f4cb8d2258f066ff56","_nodeVersion":"22.15.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-mB2Na3qIFAWwtjE5T6PTAeYNcYiDZyEZFapwO2E4KSouWKqpKEhD/DlNHYpEnw0mY6KqwALuNt89/815FPcuhQ==","shasum":"127c2fdafa8dc84691013c9eef814b98a2932466","tarball":"https://registry.npmjs.org/@ahrefs/mcp/-/mcp-0.0.11.tgz","fileCount":8,"unpackedSize":519359,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDaCFIqX4sQKwzlaa7IQFv7jbRM1x1p5bD/0RxEMLfQkgIgewHWYWOsGx7zKDMdlQkqtsYFrr6FLa2e1xOtQp5qNGY="}]},"_npmUser":{"name":"khady","email":"louis@louisroche.net"},"directories":{},"maintainers":[{"name":"khady","email":"louis@louisroche.net"},{"name":"rustykey","email":"iam@stfoo.ru"},{"name":"germes","email":"e.chemohonenko@gmail.com"},{"name":"bryanthomaschen","email":"bryanthomaschen@gmail.com"},{"name":"denstr","email":"strelkov.d.d@gmail.com"},{"name":"jchavarri","email":"javier.chavarri@gmail.com"},{"name":"zindel","email":"alexei.golovko@gmail.com"},{"name":"feihong","email":"feihong.hsu@gmail.com"},{"name":"jkvt2","email":"vince.tan@ahrefs.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.0.11_1748305218155_0.5788512319613826"},"_hasShrinkwrap":false}},"time":{"created":"2025-04-28T08:55:52.383Z","modified":"2025-05-27T00:20:18.606Z","3.0.0":"2025-04-28T08:24:29.992Z","0.1.0":"2025-04-28T08:27:00.700Z","0.0.1":"2025-04-28T08:31:23.387Z","0.0.2":"2025-04-28T08:37:22.988Z","0.0.3":"2025-04-28T08:40:21.725Z","0.0.5":"2025-04-28T08:55:52.672Z","0.0.6":"2025-05-01T06:12:26.847Z","0.0.7":"2025-05-06T02:12:24.040Z","0.0.8":"2025-05-08T09:53:15.714Z","0.0.9":"2025-05-13T02:10:58.517Z","0.0.10":"2025-05-15T02:15:47.375Z","0.0.11":"2025-05-27T00:20:18.363Z"},"author":{"name":"Ahrefs"},"license":"MIT","keywords":["mcp","model-context-protocol","openapi","ahrefs"],"description":"Ahrefs MCP server","maintainers":[{"name":"khady","email":"louis@louisroche.net"},{"name":"rustykey","email":"iam@stfoo.ru"},{"name":"germes","email":"e.chemohonenko@gmail.com"},{"name":"bryanthomaschen","email":"bryanthomaschen@gmail.com"},{"name":"denstr","email":"strelkov.d.d@gmail.com"},{"name":"jchavarri","email":"javier.chavarri@gmail.com"},{"name":"zindel","email":"alexei.golovko@gmail.com"},{"name":"feihong","email":"feihong.hsu@gmail.com"},{"name":"jkvt2","email":"vince.tan@ahrefs.com"}],"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<p align=\"center\">\n  <img src=\"images/claude1.png\" alt=\"Open the Claude menu\"/>\n</p>\n\n3. Click on `Developer` in the left panel, then `Edit Config`\n\n<p align=\"center\">\n  <img src=\"images/claude2.png\" alt=\"Open the MCP config file\"/>\n</p>\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<p align=\"center\">\n  <img src=\"images/claude3.png\" alt=\"ahrefs MCP appears under 'tools'\"/>\n</p>\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 & 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 && 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 & 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\\<username>\\.global-node-modules\n```\nReplace `<username>` with your actual Windows username.\n\n**macOS:**\n```sh\n/Users/<username>/.global-node-modules\n```\nReplace `<username>` with your macOS username.\n\n**Linux:**\n```sh\n/home/<username>/.global-node-modules\n```\nReplace `<username>` 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 && npm -v` | `node -v && 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","readmeFilename":"README.md"}