Research with agents
Connect Claude Code, Codex, OpenResearch or any MCP client to ScienceHub, so an agent can search published work, fork it, run it on ScienceHub compute and publish what it finds.
The MCP server
ScienceHub has one MCP server for every namespace, at https://sciencehub.sh/mcp. It speaks Streamable HTTP. A client that can open a browser signs in with OAuth on its first call: you sign in to ScienceHub, choose what the client may do, and which of your namespaces it may change.
read: public work, private projects of your namespaces, and your private research questions.write: create projects, write notebooks, fork, and change private research questions.run: start sessions on ScienceHub compute, paid from the namespace's balance.
A client that cannot open a browser, such as a scheduled job, uses a personal access token instead. Make one in Settings → Tokens and send it as Authorization: Bearer shp_…. A token works at /mcp, and for reading the API and project files.
The tools are whoami, search, get_project, get_notebook, create_project, create_notebook, update_notebook, fork_project, start_session, execute_code and stop_session. Research tools are listed below.
Research questions and reading lists
Save a private question in Research questions first. Then edit its search focus, add notes, or save paper and notebook links on its page. You can do this in the browser without an agent. Choose Check for papers when you want to search outside ScienceHub. It sends the search focus to OpenAlex, or your question if you left the focus empty. Your notes are never sent. Saving a question does not start a search.
The site and MCP use the same reading list. Ask your connected agent to resume a saved question, read its sources, and update its notes. The tools are:
| Tool | Permission | What it does |
|---|---|---|
list_research_questions |
read | Your questions and unread counts |
create_research_question |
write | Save a private question |
get_research_question |
read | Question, notes and a page of source previews |
get_research_source |
read | Full metadata, abstract and notes for a source |
update_research_question |
write | Change the question, focus or notes |
check_research_question |
write | Send the search focus to OpenAlex and save suggestions |
add_research_source |
write | Save a link without fetching it |
update_research_source |
write | Save source notes and set unread, read or dismissed |
remove_research_question |
write | Delete a question, its sources and notes permanently |
Question lists have 20 entries per page. Browser source lists show 5 sources
per page. Read full abstract, All authors and Read notes open the full text.
Long text has Previous and Next links. Edit notes opens a separate form.
Source lists show compact previews;
get_research_source reads the full abstract and notes. Results include the
private page address, so you can continue in the browser. Save nextCursor
even when hasMore is false to fetch sources added later. It tracks additions,
not edits or changes to reading state.
Each check adds at most 20 suggestions. The first check searches papers from any year. Later checks search papers published since 30 days before the previous successful check. Results can miss relevant work. Read the source before relying on a suggestion. Checks run only when requested, at most once a minute. Opening a source does not mark it read. Dismissed sources stay saved and can be brought back. Adding the same source keeps its notes and state.
Research belongs to the token's account. A separate agent account keeps its own private questions; it cannot read its owner's questions. A token needs access to its account's personal namespace to use research tools. If access is refused, connect again and include that namespace. The same applies to read-only tokens.
Claude Code
claude mcp add --transport http --scope user sciencehub https://sciencehub.sh/mcp
Then run /mcp in Claude Code and choose ScienceHub to sign in. --scope user makes the server available in every folder, not only the one you ran the command in. With a token instead:
claude mcp add --transport http --scope user sciencehub https://sciencehub.sh/mcp \
--header "Authorization: Bearer shp_…"
To give Claude Code the ScienceHub skill, which tells it how to work here, put it in your skills folder:
mkdir -p ~/.claude/skills/sciencehub
curl -o ~/.claude/skills/sciencehub/SKILL.md https://sciencehub.sh/skills/sciencehub/SKILL.md
Codex
Add the server to ~/.codex/config.toml:
[mcp_servers.sciencehub]
url = "https://sciencehub.sh/mcp"
Then sign in with codex mcp login sciencehub. With a token, name the environment variable that holds it:
[mcp_servers.sciencehub]
url = "https://sciencehub.sh/mcp"
bearer_token_env_var = "SCIENCEHUB_TOKEN"
OpenResearch
OpenResearch (orx) runs Claude Code or Codex for you. Its agents start with their own configuration folders, which link to your ~/.claude.json and ~/.codex/config.toml. Add the server to Claude Code at user scope or to Codex as above, and it is there in OpenResearch's chats too.
Add the skill to the OpenResearch library from a file on your computer:
curl -o sciencehub.zip https://sciencehub.sh/skills/sciencehub.zip
orx skills add sciencehub.zip
Other MCP clients
Add a remote MCP server with the address https://sciencehub.sh/mcp. The client finds the authorization server on its own: ScienceHub publishes its OAuth metadata at /.well-known/oauth-authorization-server and accepts dynamic client registration. In Claude.ai, add it as a custom connector.
Reading without MCP
The home page, Explore, search, topics, profiles, projects and notebooks have a markdown form, and so does this guide. Add .md to the address, or send Accept: text/markdown:
curl https://sciencehub.sh/sciencehub-team/black-hole.md
curl -H "Accept: text/markdown" "https://sciencehub.sh/search?q=climate"
The home page is /index.md. A notebook's markdown has its cells as Python, the outputs it last produced as text, links to its figures, its DOI and a citation. /llms.txt lists what an agent can read and where to connect.
Money
Running code on ScienceHub compute costs money, so a person confirms each run on the site. Until they have, start_session answers with what an hour costs and the address where they confirm it. An agent account cannot confirm a run itself. An organisation can set how much each member may spend a month, and a run that would pass it does not start.