Claude Desktop

\n\n1. Open the configuration file at:\n - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n - **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n On macOS you can open it from Terminal:\n ```bash\n mkdir -p ~/Library/Application\\ Support/Claude && open -a TextEdit ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n ```\n\n2. Add the Altmetric MCP server. If the file is empty, paste this (replacing the placeholder keys with your own, and removing any you don't have):\n\n ```json\n {\n \"mcpServers\": {\n \"Altmetric\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"altmetric-mcp\"],\n \"env\": {\n \"ALTMETRIC_DETAILS_API_KEY\": \"your_details_api_key_here\",\n \"ALTMETRIC_EXPLORER_API_KEY\": \"your_explorer_api_key_here\",\n \"ALTMETRIC_EXPLORER_API_SECRET\": \"your_explorer_api_secret_here\"\n }\n }\n }\n }\n ```\n\n If the file already has content, add `\"Altmetric\": { ... }` inside the existing `\"mcpServers\"` block, separated by a comma from the other entries.\n\n3. Save the file and **restart Claude Desktop** (Cmd+Q then reopen).\n\n4. Verify by asking Claude: *\"Use the Altmetric tools to look up the attention score for DOI 10.1038/nature12373\"*\n\n

\n\n

Claude Code

\n\nInstall directly from the command line:\n\n```bash\nclaude mcp add --transport stdio altmetric-mcp \\\n --env ALTMETRIC_DETAILS_API_KEY=your_details_api_key_here \\\n --env ALTMETRIC_EXPLORER_API_KEY=your_explorer_api_key_here \\\n --env ALTMETRIC_EXPLORER_API_SECRET=your_explorer_api_secret_here \\\n -- npx -y altmetric-mcp\n```\n\n

\n\n

VS Code (GitHub Copilot)

\n\nAdd to your project `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"Altmetric\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"altmetric-mcp\"],\n \"env\": {\n \"ALTMETRIC_DETAILS_API_KEY\": \"your_details_api_key_here\",\n \"ALTMETRIC_EXPLORER_API_KEY\": \"your_explorer_api_key_here\",\n \"ALTMETRIC_EXPLORER_API_SECRET\": \"your_explorer_api_secret_here\"\n }\n }\n }\n}\n```\n\nReload VS Code to apply the changes. [More information](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).\n\n

\n\n

Cursor

\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"Altmetric\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"altmetric-mcp\"],\n \"env\": {\n \"ALTMETRIC_DETAILS_API_KEY\": \"your_details_api_key_here\",\n \"ALTMETRIC_EXPLORER_API_KEY\": \"your_explorer_api_key_here\",\n \"ALTMETRIC_EXPLORER_API_SECRET\": \"your_explorer_api_secret_here\"\n }\n }\n }\n}\n```\n\n

\n\n

Other MCP clients

\n\nAny MCP-compatible client that supports stdio transport can use this server. Use the generic configuration above, adapting it to your client's config format. The command is always `npx` with args `[\"-y\", \"altmetric-mcp\"]` plus the environment variables for your API keys.\n\n

\n\n### Deploying the local server safely\n\nThe local server runs as a child process of the MCP host (Claude Desktop, Claude Code, etc.). A few things are worth knowing before you wire it into a sensitive workflow.\n\n**What the server does**\n- Read-only proxy to two Altmetric HTTP APIs over outbound HTTPS. The one exception is an idempotent `POST` to the Explorer identifier_lists endpoint (create-or-find), used internally to scope an Explorer query to a supplied set of identifiers; it creates no user-visible state and is not destructive.\n- No inbound network surface; no destructive operations.\n- Treats upstream text as untrusted: scans for prompt-injection markers, redacts suspicious matches in the LLM-facing summary, and surfaces raw values only via `structuredContent`.\n\n**What you should do**\n- **Set API keys via your MCP host's `env` block**, not via a committed `.env` file. Keys appear in URL query strings; treat them as bearer-equivalent credentials.\n- **Run with reduced privileges if your host allows it.** The server only needs outbound HTTPS to `api.altmetric.com` and `www.altmetric.com`. If your host or container runtime supports it, deny filesystem writes outside `$TMPDIR` and deny other network egress.\n- **Consider an egress allowlist (forward proxy / DLP).** If you're using the server inside an environment that processes sensitive data, route outbound traffic through a proxy that only allows the two Altmetric hosts. The server doesn't need to talk to anyone else.\n- **Respect your data-classification zone.** This server forwards tool arguments verbatim to a third party. If your prompt contains restricted or regulated data, it leaves your boundary.\n\n**What's enforced for you**\n- Outbound URLs are asserted to use `https:`.\n- Upstream responses are capped at 20 MB and 60 s.\n- Inbound tool arguments are capped at 8 MB total / 64 KB per string.\n- Filter values are validated client-side (date format, length, pagination ranges) before any upstream call.\n- Upstream error bodies are logged to stderr by SHA-256 prefix only, not verbatim.\n\nFor vulnerability reports and supported versions see [SECURITY.md](https://github.com/altmetric/altmetric-mcp/blob/main/SECURITY.md).\n\n## Troubleshooting\n\n| Problem | Solution |\n|---|---|\n| Sign-in window doesn't open / \"authentication required\" (hosted) | Your client must support remote MCP over HTTP with OAuth. In Claude Code run `/mcp` and authenticate; in Claude Desktop use the connector's **Connect** button. Make sure browser launches aren't blocked. |\n| Signed in but some tools are missing (hosted) | You only see tools for the products your Altmetric account can access (Explorer, Details Page, or both). If you expect more, contact your Altmetric account admin. |\n| `command not found: node` (local) | Node.js is not installed. [Download it here](https://nodejs.org/) (version 20.6.0 or later). |\n| Claude Desktop won't start after editing config (local) | The JSON file has a syntax error. Check for missing commas, unmatched brackets, or trailing commas. Paste it into [jsonlint.com](https://jsonlint.com) to validate. |\n| \"MCP server failed to start\" (local) | Run `npx -y altmetric-mcp` in Terminal to see the actual error. Usually a missing/invalid API key or Node.js version too old. |\n| Tools appear but return 403 errors | You're using a free-tier key with a commercial-tier tool (`get_citation_details`). Use `get_citation_counts` or `search_citations` instead. |\n| First query is slow (local) | Normal. `npx` downloads the package on first run. Subsequent uses are faster. |\n| Explorer tools fail (local) | Explorer tools need **both** `ALTMETRIC_EXPLORER_API_KEY` and `ALTMETRIC_EXPLORER_API_SECRET`. Make sure both are set. |\n\n## API Tiers\n\n### Details Page API\n- **Free Tier:** Access to `get_citation_counts` and `search_citations`\n- **Commercial Tier:** Access to all Details Page tools including `get_citation_details`\n\nIf you attempt to use `get_citation_details` with a free API key, you'll receive a 403 error.\n\n### Explorer API\n- **Institutional Access Only:** All Explorer API tools require institutional credentials\n- Provides access to research outputs and attention data across the entire Altmetric database\n- Organizations with data integrations can also access their own institutional research outputs in isolation\n- Includes advanced filtering by author, department, journal, and custom organizational metadata\n\n## Tools\n\nThis server provides eleven tools across two APIs:\n\n| Tool | API | Tier | Description |\n|---|---|---|---|\n| `get_citation_counts` | Details Page | Free | Attention metrics by identifier (DOI, PubMed ID, etc.) |\n| `get_citation_details` | Details Page | Commercial | Full mention text, author details (incl. Dimensions Researcher IDs), metadata |\n| `search_citations` | Details Page | Free | Search attention data across all outputs by timeframe |\n| `get_batch_attention_data` | Details Page | Commercial | Attention metrics for many DOIs at once, ranked |\n| `translate_identifiers` | Details Page | Commercial | Translate identifiers (DOI, PMID, etc.) to Altmetric IDs |\n| `explore_research_outputs` | Explorer | Institutional | Search and filter research outputs |\n| `explore_attention_summary` | Explorer | Institutional | Aggregated attention metrics by source and date |\n| `explore_mentions` | Explorer | Institutional | Individual mention details with filtering |\n| `explore_demographics` | Explorer | Institutional | Audience geographic and demographic data |\n| `explore_mention_sources` | Explorer | Institutional | Source/outlet analysis for mentions |\n| `explore_journals` | Explorer | Institutional | Journal metrics, rankings, and search |\n| `list_departments` | Explorer | Institutional | List your institution's departments and their IDs |\n\nAll Explorer tools additionally accept `researcher_id` and `grant_id` filters (Dimensions IDs), and an `identifiers` parameter that scopes a query to a raw list of scholarly identifiers - the server builds the corresponding identifier list for you. Explorer responses also include sentiment data (`sentiment-analysis-totals` on research outputs, `sentiment-analysis` on X/Bluesky mentions).\n\nFor detailed parameters and examples, see [TOOLS.md](https://github.com/altmetric/altmetric-mcp/blob/main/TOOLS.md).\n\n## API Documentation\n\n- **Details Page API:** https://docs.altmetric.com/details-page-api/\n- **Explorer API:** https://docs.altmetric.com/explorer-api/\n\n## License\n\nMIT\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","svg","upstream",{"_101":102,"_103":104,"_105":106,"_107":108,"_109":-5,"_110":111},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_99":86,"_100":86},"ratingAvg","reviewCount","topics",[],"license","MIT","language","JavaScript","registryName","com.altmetric.mcp/altmetric-mcp","homepage","packages",[112],{"_113":114,"_115":21,"_76":77},"registryType","npm","identifier","ENV",{"_118":119,"_120":121,"_122":123},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]

altmetric mcp