ads-bib
YifZhou/ads-bib
Recupera BibTeX verificado da NASA ADS para Claude e Codex
Ver no GitHubMCP server que recupera entradas BibTeX verificadas diretamente da NASA ADS, integrando-se ao Claude Desktop e OpenAI Codex. Oferece busca com sintaxe completa e citações formatadas automaticamente, com dados sempre atualizados via API ao vivo.
Instalação
npx convez-ai YifZhou/ads-bib1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerar citações BibTeX automaticamente durante escrita acadêmica
- Buscar referências bibliográficas com queries avançadas (autor, título, ano, etc)
- Integrar gestão de referências em fluxo de trabalho com IA
Veredito

Solução sólida e bem documentada para pesquisadores que precisam de citações verificadas em tempo real. Exige configuração técnica (token API, ambiente Python), mas elimina risco de bibcodes fabricados.
README
A tradução para o português deste README ainda está na fila.
ads-bib
A local MCP server that retrieves verified BibTeX entries directly from NASA ADS, with a skill for Claude Desktop and OpenAI Codex. Every entry comes from a live ADS API call — no fabricated bibcodes or citation keys.
Features
- Search NASA ADS with full query syntax (
author:,title:,abs:,year:,bibstem:, etc.) - Cite keys formatted as
LastYYYY(e.g.Zhou2021), witha/b/csuffixes for same-author-year collisions (e.g.Zhou2022a,Zhou2022b) - BibTeX output is verbatim from ADS — no fields added, removed, or reformatted
What you need
- Claude Desktop or OpenAI Codex (CLI or desktop app)
- Python 3.10+ (Conda recommended)
- A NASA ADS API token (free)
Step 1 — Get a NASA ADS API token
- Go to https://ui.adsabs.harvard.edu and sign in (or create a free account).
- Navigate to Settings → API Token.
- Copy the token — you'll need it in Step 4.
Step 2 — Create a Conda environment
We recommend a dedicated environment to keep dependencies isolated:
conda create -n ads-bib python=3.11
conda activate ads-bib
pip install mcp requests
Note the full path to this environment's Python — you'll need it in Step 5:
conda activate ads-bib
which python # e.g. /Users/yourname/opt/anaconda3/envs/ads-bib/bin/python
Step 3 — Clone this repo
git clone https://github.com/YifZhou/ads-bib.git ~/Documents/ads-bib
Step 4 — Add your API token
Open ads_mcp_server.py and replace the placeholder:
API_KEY = "YOUR_ADS_API_TOKEN_HERE"
with your actual token from Step 1.
Step 5 — Register the MCP server
Claude Desktop
Open the config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Add the "ads" entry inside "mcpServers":
{
"mcpServers": {
"ads": {
"command": "/Users/yourname/opt/anaconda3/envs/ads-bib/bin/python",
"args": ["/Users/yourname/Documents/ads-bib/ads_mcp_server.py"]
}
}
}
If you already have other MCP servers configured, add "ads" alongside them — don't replace the existing entries.
OpenAI Codex (CLI and desktop app)
Codex supports local stdio MCP servers natively, and the CLI and desktop app share the same config. The quickest setup is the codex mcp add command:
codex mcp add ads -- /Users/yourname/opt/anaconda3/envs/ads-bib/bin/python /Users/yourname/Documents/ads-bib/ads_mcp_server.py
Or edit ~/.codex/config.toml directly:
[mcp_servers.ads]
command = "/Users/yourname/opt/anaconda3/envs/ads-bib/bin/python"
args = ["/Users/yourname/Documents/ads-bib/ads_mcp_server.py"]
To verify the server is connected, run /mcp inside a Codex session.
Step 6 — Install the skill
Claude Desktop
- Download
ads-bib.skillfrom this repo. - Open Claude Desktop → Settings → Skills.
- Drag and drop
ads-bib.skillinto the Skills panel.
OpenAI Codex (CLI and desktop app)
The .skill file is a zip archive. Unzip it and copy the skill directory to ~/.codex/skills/. This works for both the CLI and the desktop app — they share the same skills directory.
unzip ads-bib.skill -d /tmp/ads-bib-extracted
mkdir -p ~/.codex/skills
cp -r /tmp/ads-bib-extracted/ads-bib ~/.codex/skills/
Codex will automatically discover the skill at ~/.codex/skills/ads-bib/SKILL.md on next launch.
Step 7 — Restart your AI assistant
Quit and relaunch Claude Desktop or Codex. The ads MCP server should now be connected and the skill active.
Usage
Ask naturally — no special syntax needed:
Find the bib entry for the Morley 2012 cloud paper
Search relevant papers in the last five years about accreting planets.
Find all my first-author papers and output the bib entries
The assistant will call ads_search to find matching papers and ads_bibtex to retrieve the entries, then output a ready-to-use BibTeX block with LastYYYY cite keys.
File overview
| File | Purpose |
|---|---|
SKILL.md | Skill instructions (also bundled inside ads-bib.skill) |
ads_mcp_server.py | Local Python MCP server — wraps the ADS search and BibTeX export API |
ads-bib.skill | Packaged skill file for Claude Desktop and Codex |
Troubleshooting
The ads tools don't appear
- Check that the config entry is correctly formatted and in the right file for your client.
- Verify the Python path points to the
ads-bibconda environment:conda activate ads-bib && which python. - Confirm
mcpandrequestsare installed in that environment:pip list | grep -E "mcp|requests". - Restart the AI assistant after any config change.
- For Codex: run
/mcpinside a session to list active servers.
HTTP 401 error
- Your API token is invalid or expired. Get a new one from https://ui.adsabs.harvard.edu/user/settings/token and update
ads_mcp_server.py.
HTTP 429 error
- ADS rate limit hit. Wait a few seconds and retry. The free tier allows 5,000 requests/day.
Zero results
- Broaden the query: remove the year filter, or switch from
title:toabs:with 3–4 distinctive keywords.