The OpenAlex MCP connector routes your AI agent's tool calls to OpenAlex's own MCP server through Scalekit. Each user signs in to OpenAlex once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 18 tools.
- Tools
- 18
- What they doRead · write · destructive
- 16 · 1 · 116 read1 write1 destructive
- Users sign in with
- OAuth
- OAuth app
- Your own OpenAlex MCP server app
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the OpenAlex MCP connection
In AgentKit > Connections, create an OpenAlex MCP connection and copy its redirect URI. The name you give it is the
connection_nameyour code passes. See Configure connections.Register an OAuth app
OpenAlex MCP server connections use your own OAuth app. Register one with OpenAlex MCP server and add the redirect URI you copied.
Then enter the app's Client ID and Client Secret on the OpenAlex MCP connection.
Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'openalexmcp'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize OpenAlex MCP:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'openalexmcp_analyze_works',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "openalexmcp"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize OpenAlex MCP:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="openalexmcp_analyze_works",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user signs in once. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolopenalexmcp_analyze_worksBuild a one-call profile of any set of works defined by a query and/or filters: an institution's output, a funder's portfolio, an author's career, a topic, a country, a journal.Read-onlyAnalyze a set of works
Build a one-call profile of any set of works defined by a query and/or filters: an institution's output, a funder's portfolio, an author's career, a topic, a country, a journal. Returns total works, open-access share by status, share of works in the top 10% and top 1% most-cited (field-normalized), counts by year and by type, and the top fields, topics, institutions, countries, sources, funders and authors, plus international and industry collaboration shares. Use it for research-office, library, and funder reporting questions ("summarize our 2024 research", "how much of NIH-funded work at UW is open access", "who does MIT collaborate with on AI"). Pick sections to keep the response small. Keyword queries only (no semantic mode). Each section costs one cheap API call.
Inputs
any_topic_idsarray- OpenAlex topic IDs (OR): works that carry one of these among ANY of their topics, primary or not (typically ~3x as many works as topic_ids). OQL: `where topics is (T10102)`.
author_idsarray- OpenAlex author IDs (e.g. A5067184382). Resolve names with search_entities first.
core_sources_onlyboolean- Only works published in 'core' sources: reputable, well-indexed journals and repositories (see https://help.openalex.org/data/sources/). Useful to exclude low-quality venues.
countriesarray- ISO-3166 alpha-2 country codes of author institutions (OR), e.g. ["US","GB"]. Not supported with semantic search.
from_yearinteger- Earliest publication year, inclusive (e.g. 2020).
funder_idsarray- OpenAlex funder IDs (e.g. F4320332161).
include_retractedboolean- Include retracted works. Default false: retracted works are hidden and the response says so (retracted_works). Also honoured with oql, where the default leaves them out unless the query says otherwise (the echo then reads `it's not retracted`, or `non-retracted works` in the new form).
institution_idsarray- OpenAlex institution IDs (e.g. I27837315). Matches any author's affiliation.
is_traditionalboolean- true = only traditional scholarly works: the kinds the scholarly record has long counted (articles, books, chapters, theses, conference papers, preprints, reviews, editorials, letters...). false = only the rest (datasets, software, reports, abstracts, paratext...). Not the same as peer-reviewed: preprints and editorials are traditional.
keyword_idsarray- OpenAlex keyword ids (e.g. microplastics, human-health), any of them (OR). Find them with find_keywords. Keywords widen a text search; they do not replace it.
languagestring- ISO-639-1 language code, e.g. "en".
min_citationsinteger- Minimum cited_by_count. Not supported with semantic search.
oa_statusarray- Only these open-access statuses (OR).
open_access_onlyboolean- Only works with a free-to-read copy.
publisher_idsarray- OpenAlex publisher IDs (e.g. P4310319908).
querystring- Optional keyword search text (Boolean supported).
raw_filterstring- Escape hatch: extra OpenAlex filter expression appended verbatim, using the syntax documented at https://help.openalex.org/api/filtering/ (e.g. "has_abstract:true,primary_topic.field.id:17"). Combined with the structured filters above using AND.
search_instring- Where keyword/exact queries match. title_abstract_keywords (default, what openalex.org searches) matches title and abstract text, and also works tagged with a keyword that a phrase in the query names (catches other wordings, other languages and works with no abstract; every other word must still be in the text); title_and_abstract matches the text only; fulltext also matches the body text of ~100M works, plus keywords (broader, more noise; large reviews that merely mention a term will rank high); title matches titles only. Ignored for semantic mode.one of
title_abstract_keywordstitle_and_abstractfulltexttitle sectionsarray- Which sections to compute. Default: all.
source_idsarray- OpenAlex source (journal/repository) IDs (e.g. S137773608).
to_yearinteger- Latest publication year, inclusive.
top_ninteger- How many entries per top_* list. Default 10.
topic_idsarray- OpenAlex topic IDs (e.g. T10102), any of them (OR): works whose PRIMARY topic is one of these. Same meaning as OQL's `in the topic`, group_by topic and analyze_works top_topics. For works that carry the topic among any of their (up to 3) topics, use any_topic_ids.
typesarray- Only these work types (OR). Common: article, review, preprint, book-chapter, dataset.
openalexmcp_calculate_worksRun an OQL calculation and get the calculated groups: split a set of works by one to three fields, named values, searches, conditions or bins, and calculate count, mean/median/sum/min/max of a number, percent of a yes/no field, or each group's share.Read-onlyCalculate over works (OQL pipeline)
Run an OQL calculation and get the calculated groups: split a set of works by one to three fields, named values, searches, conditions or bins, and calculate count, mean/median/sum/min/max of a number, percent of a yes/no field, or each group's share. Write it as a pipeline: get works where <conditions>; then, group those works by <field>; finally, summarize using <measures>. For one row per author, institution, source, publisher, funder, country or topic, start with them and say which works count, e.g. get authors at [University of British Columbia](I141945490) since 2022 who published works where title-abstract has kelp; then, summarize each author using count and mean FWCI (`at` reads the author's own record; `in [Asia](Q48)` for institutions; then, group each author's works by year for a further split). Or compare named things in one step, e.g. get works where topic is [CRISPR and Genetic Engineering](T10878); then, compare institution [Massachusetts Institute of Technology](I63966007) versus [Stanford University](I97018004) versus [Harvard University](I136199984) using count, mean FWCI, and percent open access. The full guide is the OQL reference in the server instructions (read_docs topic oql). Check a new query with check_oql first (free: limits with fixes, time estimate, price). Returns one row per group, keyed by the OQL words of each calculation (count, mean FWCI, ...), nested splits under groups, the summary (summary.all for the whole starting set; with two or more splits, summary.splits with each split's groups on their own, computed from the works: read these, never sum or average group rows), groups_count and next_page, the price, the canonical OQL and a reproduce_url. A query with no split or calculation gets then, summarize using count; a query that starts from authors, institutions, sources, topics, funders or publishers with no split lists them with their own fields. Retracted works are left out unless include_retracted=true or the query says otherwise.
Inputs
oqlstringrequired- A pipeline OQL query, e.g. get works where country is [Kenya](KE) and published since 2015; then, group those works by year; finally, summarize using percent open access.
include_retractedboolean- Include retracted works. Default false.
limitinteger- Groups per page (the outer split), 1-200. Default 50. Groups come back by count.
pageinteger- Page of groups. Default 1.
sortstring- Order this page's rows by a calculated column, e.g. "mean FWCI" (descending). OQL itself has no sort; the API picks each page's groups by count.
openalexmcp_check_oqlFree check of any OQL query before running it, the calculation pipelines above all: whether it is valid, every problem with its fix (a parse error, a fourth split, too many groups, too slow), the time estimate against the ~10-second budget, the price in credits and USD, and the canonical text with each entity's name in brackets so you can confirm the IDs mean what you think.Read-onlyCheck an OQL query (free)
Free check of any OQL query before running it, the calculation pipelines above all: whether it is valid, every problem with its fix (a parse error, a fourth split, too many groups, too slow), the time estimate against the ~10-second budget, the price in credits and USD, and the canonical text with each entity's name in brackets so you can confirm the IDs mean what you think. The query is checked as calculate_works would run it (retracted works left out unless include_retracted=true). When it is not valid, apply the fix and check again.
Inputs
oqlstringrequired- The OQL query to check.
include_retractedboolean- Check it with retracted works included. Default false, as the tools run it.
openalexmcp_find_candidate_worksWorks that are probably this author's but are not on their profile, from up to three sources: (1) name: the website's name ladder over raw bylines (as typed, reversed, initials, then looser word order) with a surname-plus-given-name gate, ranked by how much of the name the byline matches; (2) orcid: works carrying the ORCID in OpenAlex plus works listed on the public ORCID record (readable without login unless the author made them private); (3) siblings: other author profiles with the same name, with overlap signals, which may be duplicates of this person.Read-onlyFind works that may belong to an author
Works that are probably this author's but are not on their profile, from up to three sources: (1) name: the website's name ladder over raw bylines (as typed, reversed, initials, then looser word order) with a surname-plus-given-name gate, ranked by how much of the name the byline matches; (2) orcid: works carrying the ORCID in OpenAlex plus works listed on the public ORCID record (readable without login unless the author made them private); (3) siblings: other author profiles with the same name, with overlap signals, which may be duplicates of this person. Every work reports this_authorship (the byline that would be attached, with affiliations and coauthors) so the user can be asked about anything unclear. Pass alternate names (from get_my_account, the profile, or a CV) one call at a time; for common names add institution, topic or year filters.
Inputs
author_idstringrequired- The profile being curated (A…). Works already on it are excluded.
any_topic_idsarray- Narrow the name search to works that carry one of these topics (T…) among any of their topics, not only the primary one (a wide net for finding a person's works).
from_yearinteger- No description.
institution_idsarray- Narrow the name search to works with an author at these institutions (I…).
limitinteger- Max works per source. Default 25.
namestring- Name to search bylines for. Default: the profile's display name. Try each alternate name the person publishes under.
orcidstring- The author's ORCID, if they gave one.
sourcesarray- Which sources to run. Default: all that apply.
to_yearinteger- No description.
openalexmcp_find_keywordsFind the OpenAlex keywords for a topic, the first step of a thorough (high-recall) search.Read-onlyFind keywords
Find the OpenAlex keywords for a topic, the first step of a thorough (high-recall) search. OpenAlex tags works with keywords (e.g. microplastics, human-health, antimicrobial-resistance) that also catch works using other wordings, other languages, or no abstract at all. search_works and keyword_search already match the keywords that the search's own phrases name; use this to find keywords that mean a facet under other names. Give the topic as a sentence (description) and, for better coverage, each facet's main phrase and synonyms (phrases). Returns candidate keywords with a match score, how many works carry each, and their three most-cited titles, so you can keep the ones that mean each facet and drop the rest. Then pass them to keyword_search. Costs about $0.01 (one /text/keywords call) plus a few cheap lookups.
Inputs
descriptionstringrequired- The topic in a sentence or short paragraph, e.g. "how microplastics affect human health". At least 20 characters to be matched as text.
per_phraseinteger- Keyword-name matches kept per phrase. Default 5.
phrasesarray- Short names to look up among keyword names: each facet's main phrase and a synonym or two, e.g. ["microplastics", "nanoplastics", "human health"].
openalexmcp_get_entityFetch the full profile of one non-work entity by OpenAlex ID, or by ORCID (authors), ROR (institutions), or ISSN (sources).Read-onlyGet author, institution, source, topic, funder or publisher
Fetch the full profile of one non-work entity by OpenAlex ID, or by ORCID (authors), ROR (institutions), or ISSN (sources). Includes works and citation counts, h-index, works/citations by year, top topics, affiliation history (authors), and identifiers.
Inputs
entity_typestringrequired- Which kind of entity the ID refers to.one of
authorsinstitutionssourcestopicsfunderspublishers idstringrequired- OpenAlex ID (A5067184382, I27837315, S137773608, T10102, F…, P…), ORCID, ROR, or ISSN.
openalexmcp_get_my_accountWho is connected: name, email addresses (and which are verified), which API key this connection spends (personal or organization), the author profile this account has claimed (with a compact summary: names, institutions, topics, works count), the claim's status, and claim_eligibility: "instant" means a claim from this account is approved immediately (a verified academic, institutional or government email), "review" means the claim needs ORCID sign-in or a link to one of the user's papers on the profile that lists the account email (checked automatically within minutes; a web page alone never passes).Read-onlyGet my OpenAlex account
Who is connected: name, email addresses (and which are verified), which API key this connection spends (personal or organization), the author profile this account has claimed (with a compact summary: names, institutions, topics, works count), the claim's status, and claim_eligibility: "instant" means a claim from this account is approved immediately (a verified academic, institutional or government email), "review" means the claim needs ORCID sign-in or a link to one of the user's papers on the profile that lists the account email (checked automatically within minutes; a web page alone never passes). Call this first for anything about the user's own profile.
Inputs
This tool takes no inputs.
openalexmcp_get_workFetch the full record for one scholarly work by OpenAlex ID (W2741809807), DOI (10.7717/peerj.4375 or a doi.org URL), arXiv id (2305.18290, arXiv:2305.18290v2 or an arxiv.org URL), PMID, or PMCID.Read-onlyGet work
Fetch the full record for one scholarly work by OpenAlex ID (W2741809807), DOI (10.7717/peerj.4375 or a doi.org URL), arXiv id (2305.18290, arXiv:2305.18290v2 or an arxiv.org URL), PMID, or PMCID. Returns the authors with affiliations and ORCIDs (all of them up to 100; a bigger collaboration lists the first 100, the last and the corresponding authors, numbered, with authors_total), the full abstract, venue, open-access links, topics, keywords, funding, citations in every year the API counts, and related works.
Inputs
idstringrequired- OpenAlex work ID, DOI, arXiv id, PMID, or PMCID.
openalexmcp_group_worksAggregate works matching a query and/or filters, counting them by one dimension: author, institution, institution_type, country, source (journal), publisher, funder, year, type, is_traditional (traditional scholarly works vs the rest), topic, subfield, field, domain, keyword, oa_status, is_oa, top_10_percent, top_1_percent, language, or sdg.Read-onlyCount works by author, institution, year, topic, etc.
Aggregate works matching a query and/or filters, counting them by one dimension: author, institution, institution_type, country, source (journal), publisher, funder, year, type, is_traditional (traditional scholarly works vs the rest), topic, subfield, field, domain, keyword, oa_status, is_oa, top_10_percent, top_1_percent, language, or sdg. Answers "who are the top authors on X", "which institutions publish most on Y", "how has research on Z grown per year", "which journals carry the most papers on W", "who does institution A collaborate with" (institution_ids + group_by institution). Returns each group's ID, display name and work count, sorted by count. Keyword/exact queries aggregate over all matching works; semantic queries aggregate over the 50 most relevant works only. For two or three dimensions in one call (by year and country, by field and open access status) or numbers beyond the count (mean FWCI, percent open access, share), use calculate_works instead of one group_works call per value. Accepts an OQL query in `oql` for complex selections (the group by is added from group_by if the query has none). Note: group_by author over institution-filtered works also counts co-authors from other institutions; for "researchers AT institution X on topic Y" use search_entities with institution_ids and topic_ids instead.
Inputs
group_bystringrequired- Dimension to count by.one of
authorinstitutioninstitution_typecountrysourcepublisherfunderyeartypeis_traditionaltopicsubfieldfielddomainkeywordoa_statusis_oatop_10_percenttop_1_percentlanguagesdg any_topic_idsarray- OpenAlex topic IDs (OR): works that carry one of these among ANY of their topics, primary or not (typically ~3x as many works as topic_ids). OQL: `where topics is (T10102)`.
author_idsarray- OpenAlex author IDs (e.g. A5067184382). Resolve names with search_entities first.
core_sources_onlyboolean- Only works published in 'core' sources: reputable, well-indexed journals and repositories (see https://help.openalex.org/data/sources/). Useful to exclude low-quality venues.
countriesarray- ISO-3166 alpha-2 country codes of author institutions (OR), e.g. ["US","GB"]. Not supported with semantic search.
from_yearinteger- Earliest publication year, inclusive (e.g. 2020).
funder_idsarray- OpenAlex funder IDs (e.g. F4320332161).
include_retractedboolean- Include retracted works. Default false: retracted works are hidden and the response says so (retracted_works). Also honoured with oql, where the default leaves them out unless the query says otherwise (the echo then reads `it's not retracted`, or `non-retracted works` in the new form).
institution_idsarray- OpenAlex institution IDs (e.g. I27837315). Matches any author's affiliation.
is_traditionalboolean- true = only traditional scholarly works: the kinds the scholarly record has long counted (articles, books, chapters, theses, conference papers, preprints, reviews, editorials, letters...). false = only the rest (datasets, software, reports, abstracts, paratext...). Not the same as peer-reviewed: preprints and editorials are traditional.
keyword_idsarray- OpenAlex keyword ids (e.g. microplastics, human-health), any of them (OR). Find them with find_keywords. Keywords widen a text search; they do not replace it.
languagestring- ISO-639-1 language code, e.g. "en".
limitinteger- Max groups to return, 1-200. Default 25.
min_citationsinteger- Minimum cited_by_count. Not supported with semantic search.
modestring- Search mode. Default keyword.one of
keywordsemanticexact oa_statusarray- Only these open-access statuses (OR).
open_access_onlyboolean- Only works with a free-to-read copy.
oqlstring- OQL query selecting the works to count (see search_works). Mutually exclusive with query and the structured filters.
publisher_idsarray- OpenAlex publisher IDs (e.g. P4310319908).
querystring- Optional search text (same as search_works).
raw_filterstring- Escape hatch: extra OpenAlex filter expression appended verbatim, using the syntax documented at https://help.openalex.org/api/filtering/ (e.g. "has_abstract:true,primary_topic.field.id:17"). Combined with the structured filters above using AND.
search_instring- Where keyword/exact queries match. title_abstract_keywords (default, what openalex.org searches) matches title and abstract text, and also works tagged with a keyword that a phrase in the query names (catches other wordings, other languages and works with no abstract; every other word must still be in the text); title_and_abstract matches the text only; fulltext also matches the body text of ~100M works, plus keywords (broader, more noise; large reviews that merely mention a term will rank high); title matches titles only. Ignored for semantic mode.one of
title_abstract_keywordstitle_and_abstractfulltexttitle source_idsarray- OpenAlex source (journal/repository) IDs (e.g. S137773608).
to_yearinteger- Latest publication year, inclusive.
topic_idsarray- OpenAlex topic IDs (e.g. T10102), any of them (OR): works whose PRIMARY topic is one of these. Same meaning as OQL's `in the topic`, group_by topic and analyze_works top_topics. For works that carry the topic among any of their (up to 3) topics, use any_topic_ids.
typesarray- Only these work types (OR). Common: article, review, preprint, book-chapter, dataset.
openalexmcp_keyword_searchBuild and measure a thorough search: each facet matches on its text (over titles, abstracts and the keywords the text names) OR on the keywords you chose for it, and all facets must match.Read-onlyKeyword-aware search
Build and measure a thorough search: each facet matches on its text (over titles, abstracts and the keywords the text names) OR on the keywords you chose for it, and all facets must match. Returns the combined OQL with a reproduce_url, and counts for every part: the search alone (what search_works finds for the facets' text), what the chosen keywords add, the combined total, and each facet's text, keyword and keyword-only counts, plus random samples of the whole search and of the works found only through keywords, so you can check precision. Filters (open access, years, types, language, any OQL condition) apply to every count. Use after find_keywords; then list the results with search_works(oql=<combined oql>). Every facet should have text; give a facet keyword_ids only when a keyword really means it.
Inputs
facetsarrayrequired- The parts of the topic that must all hold, each with its text and keywords.
extra_oqlstring- Any further OQL condition ANDed onto every count, e.g. country is (BR) or "citation count is at least 10".
from_yearinteger- Earliest publication year, inclusive.
include_retractedboolean- Include retracted works. Default false.
languagestring- ISO-639-1 language code, e.g. "en". Note that keywords are what find works in other languages.
open_access_onlyboolean- Only works with a free-to-read copy.
sample_sizeinteger- Random works to show from the keyword-only additions (up to 8 are also drawn from the whole search). Default 8.
to_yearinteger- Latest publication year, inclusive.
typesarray- Only these work types (OR), e.g. ["article","review"].
openalexmcp_list_citationsList works connected to a given work: direction="citing" (default) returns works that cite it; "references" returns the works it cites; "related" returns OpenAlex's related works (similar topic and citation neighbourhood).Read-onlyList citations
List works connected to a given work: direction="citing" (default) returns works that cite it; "references" returns the works it cites; "related" returns OpenAlex's related works (similar topic and citation neighbourhood). Useful for tracing influence, finding follow-up studies, or reading a paper's bibliography. Supports the same year/type/open-access filters as search_works.
Inputs
work_idstringrequired- OpenAlex work ID or DOI of the anchor work.
any_topic_idsarray- OpenAlex topic IDs (OR): works that carry one of these among ANY of their topics, primary or not (typically ~3x as many works as topic_ids). OQL: `where topics is (T10102)`.
author_idsarray- OpenAlex author IDs (e.g. A5067184382). Resolve names with search_entities first.
core_sources_onlyboolean- Only works published in 'core' sources: reputable, well-indexed journals and repositories (see https://help.openalex.org/data/sources/). Useful to exclude low-quality venues.
countriesarray- ISO-3166 alpha-2 country codes of author institutions (OR), e.g. ["US","GB"]. Not supported with semantic search.
directionstring- citing (default), references, or related.one of
citingreferencesrelated from_yearinteger- Earliest publication year, inclusive (e.g. 2020).
funder_idsarray- OpenAlex funder IDs (e.g. F4320332161).
include_abstractsboolean- Include a truncated abstract per result. Default false.
include_retractedboolean- Include retracted works. Default false: retracted works are hidden and the response says so (retracted_works). Also honoured with oql, where the default leaves them out unless the query says otherwise (the echo then reads `it's not retracted`, or `non-retracted works` in the new form).
institution_idsarray- OpenAlex institution IDs (e.g. I27837315). Matches any author's affiliation.
is_traditionalboolean- true = only traditional scholarly works: the kinds the scholarly record has long counted (articles, books, chapters, theses, conference papers, preprints, reviews, editorials, letters...). false = only the rest (datasets, software, reports, abstracts, paratext...). Not the same as peer-reviewed: preprints and editorials are traditional.
keyword_idsarray- OpenAlex keyword ids (e.g. microplastics, human-health), any of them (OR). Find them with find_keywords. Keywords widen a text search; they do not replace it.
languagestring- ISO-639-1 language code, e.g. "en".
limitinteger- Results per page, 1-50. Default 15.
min_citationsinteger- Minimum cited_by_count. Not supported with semantic search.
oa_statusarray- Only these open-access statuses (OR).
open_access_onlyboolean- Only works with a free-to-read copy.
pageinteger- Page number. Default 1.
publisher_idsarray- OpenAlex publisher IDs (e.g. P4310319908).
raw_filterstring- Escape hatch: extra OpenAlex filter expression appended verbatim, using the syntax documented at https://help.openalex.org/api/filtering/ (e.g. "has_abstract:true,primary_topic.field.id:17"). Combined with the structured filters above using AND.
sortstring- Default cited_by_count (descending).one of
cited_by_countpublication_date source_idsarray- OpenAlex source (journal/repository) IDs (e.g. S137773608).
to_yearinteger- Latest publication year, inclusive.
topic_idsarray- OpenAlex topic IDs (e.g. T10102), any of them (OR): works whose PRIMARY topic is one of these. Same meaning as OQL's `in the topic`, group_by topic and analyze_works top_topics. For works that carry the topic among any of their (up to 3) topics, use any_topic_ids.
typesarray- Only these work types (OR). Common: article, review, preprint, book-chapter, dataset.
openalexmcp_list_my_curationsThe corrections this account has submitted and their status: pending (waiting: submitted under a week ago, or not checked yet), applied (seen live once; a later correction to the same item can change it), superseded (a newer correction to the same item, by this user or someone else, replaced it, so it will never apply; superseded_by names that correction), timed_out (over a week old and checked, but not seen live yet; not an error, checks continue and it can still apply), or not_applied (the nightly data build will not apply it as it stands and the data does not show it: walden.reason says why, e.g.Read-onlyList my curations
The corrections this account has submitted and their status: pending (waiting: submitted under a week ago, or not checked yet), applied (seen live once; a later correction to the same item can change it), superseded (a newer correction to the same item, by this user or someone else, replaced it, so it will never apply; superseded_by names that correction), timed_out (over a week old and checked, but not seen live yet; not an error, checks continue and it can still apply), or not_applied (the nightly data build will not apply it as it stands and the data does not show it: walden.reason says why, e.g. work_merged, work_deleted, name_not_on_byline, profile_deleted; closed, but it turns applied by itself if a later build serves it). Rows the nightly build has seen carry walden: {outcome, reason, detail, effect_live, run_date}; detail names the work a merged work became or the correction that won. Unapplied = pending plus timed_out. Each row carries a plain-language description. Use it to report progress or to find a curation_id to cancel.
Inputs
entitystring- works = add/remove work curations; authors = name and ORCID changes.one of
worksauthors limitinteger- Rows per page. Default 25.
pageinteger- No description.
statusarray- Only these statuses. Default: all.
openalexmcp_read_docsReturn a canonical OpenAlex documentation page, bundled from help.openalex.org: oql (OQL: the OpenAlex Query Language (overview)); oql_spec (OQL specification (normative, every rule and error code)); api_quick_reference (OpenAlex API quick reference for agents (entities, filters, syntax)); fixing_authors (Fixing author profiles: claiming, adding and removing works, merging duplicates); author_curation (Author curation API: the exact curation payloads and how they are applied).Read-onlyRead OpenAlex documentation
Return a canonical OpenAlex documentation page, bundled from help.openalex.org: oql (OQL: the OpenAlex Query Language (overview)); oql_spec (OQL specification (normative, every rule and error code)); api_quick_reference (OpenAlex API quick reference for agents (entities, filters, syntax)); fixing_authors (Fixing author profiles: claiming, adding and removing works, merging duplicates); author_curation (Author curation API: the exact curation payloads and how they are applied). Use oql_spec when an OQL query is rejected and the fix-it isn't enough, api_quick_reference for entity fields and filter names, and fixing_authors before curating a profile.
Inputs
topicstringrequired- Which page.one of
oqloql_specapi_quick_referencefixing_authorsauthor_curation sectionstring- Optional heading text; returns only that section (case-insensitive substring match on headings).
openalexmcp_resolve_referencesCheck up to 25 references against OpenAlex in one call and report what each one matched.Read-onlyResolve references
Check up to 25 references against OpenAlex in one call and report what each one matched. Each item may be a DOI, PMID, OpenAlex ID, or a free-text citation (e.g. "Piwowar et al. (2018) The state of OA. PeerJ"). IDs are looked up exactly; free-text citations are matched on title with a confidence rating (exact, likely, uncertain, none) and match_p, the probability that the matched work is the one cited. Use it to verify a bibliography, detect fabricated or garbled citations, fill in missing DOIs, or turn a reading list into OpenAlex IDs.
Inputs
referencesarrayrequired- Citations to resolve, one per item.
author_idstring- Profile curation: an author ID (A…). Each matched work then reports on_profile (already attributed to that author) and authorship_match (the byline to attach, with raw_author_name for submit_curations add_work), so a CV or publication list can be reconciled against the profile.
openalexmcp_search_entitiesFind OpenAlex entities by name and/or filters, returning IDs plus a short profile.Read-onlySearch authors, institutions, sources, topics, funders, publishers
Find OpenAlex entities by name and/or filters, returning IDs plus a short profile. Entity types: authors (researchers), institutions (universities, labs, companies), sources (journals, conferences, repositories), topics (research areas), funders, publishers. Use it to resolve a name to an ID before filtering works, or as a directory. It is the right tool for expert finding: authors currently at an institution working on a topic (institution_ids + topic_ids, sort by works_count or h_index; each result reports works_in_topic), journals in a field that are open access (sources + topic_ids + is_oa), institutions of a type in a country. Author results include current institutions, h-index and top topics so the right person can be picked when names collide.
Inputs
entity_typestringrequired- Which kind of entity to search.one of
authorsinstitutionssourcestopicsfunderspublishers countrystring- ISO country code: authors (current institution), institutions, sources, funders, publishers.
has_orcidboolean- authors: only profiles with an ORCID.
institution_idsarray- authors: current institution (includes child institutions). institutions: restrict to these or their children.
is_in_doajboolean- sources: only venues listed in DOAJ.
is_oaboolean- sources: only fully open-access venues.
limitinteger- Results per page, 1-50. Default 10.
max_apc_usdinteger- sources: article processing charge at most this many USD (0 = no APC).
min_h_indexinteger- authors/sources/institutions: minimum h-index.
min_works_countinteger- Minimum number of works.
pageinteger- Page number. Default 1.
querystring- Name or partial name, e.g. "Jennifer Doudna", "MIT", "Nature Communications", "CRISPR". Optional when filters are given.
raw_filterstring- Escape hatch: extra filter expression appended verbatim, using the syntax at https://help.openalex.org/api/filtering/ for this entity type.
sortstring- Default: relevance when there is a query, otherwise works_count. Descending.one of
relevanceworks_countcited_by_counth_index topic_idsarray- authors/sources/institutions: only those with works carrying these topics (T…) among any of their topics; works_in_topic counts those works (the any_topic_ids meaning in the works tools, not their primary-topic topic_ids).
typestring- institutions: education, healthcare, company, government, nonprofit, facility, funder, archive, other. sources: journal, repository, conference, ebook platform, book series.
openalexmcp_search_worksSearch OpenAlex for scholarly works (papers, preprints, books, datasets).Read-onlySearch works
Search OpenAlex for scholarly works (papers, preprints, books, datasets). mode="keyword" (default) supports Boolean syntax: AND, OR, NOT, "quoted phrases", parentheses. By default it searches titles, abstracts and keywords: a phrase in the query that names an OpenAlex keyword also matches works carrying that keyword (search_in to change). Relevance-sorted results are reranked by default: the top 100 are reordered by how well each work answers the query, so the first results are the most on-topic ones and rerank_score says how sure the reranker is (rerank=false to turn it off). mode="semantic" matches by meaning and is best for descriptive or long queries (up to 2,000 characters; max 50 results; no min_citations/countries filters). mode="exact" matches words without stemming. Omit query to list works by filters alone (e.g. everything by an author, institution or funder). For anything the structured parameters can't express (nested Boolean groups across fields, exclusions, proximity, exact phrases, wildcards) pass an OQL query in `oql` instead; the OQL reference is in the server instructions and at https://help.openalex.org/access/oql/. Set preview=true to get only the result count, the canonical OQL and a small sample, which is the cheap way to tune a query before running it. Every response includes the canonical OQL and a reproduce_url. Returns compact records: title, year, authors (first 5), venue, citations, FWCI, open-access link, primary topic, truncated abstract. Use get_work for a full record.
Inputs
any_topic_idsarray- OpenAlex topic IDs (OR): works that carry one of these among ANY of their topics, primary or not (typically ~3x as many works as topic_ids). OQL: `where topics is (T10102)`.
author_idsarray- OpenAlex author IDs (e.g. A5067184382). Resolve names with search_entities first.
core_sources_onlyboolean- Only works published in 'core' sources: reputable, well-indexed journals and repositories (see https://help.openalex.org/data/sources/). Useful to exclude low-quality venues.
countriesarray- ISO-3166 alpha-2 country codes of author institutions (OR), e.g. ["US","GB"]. Not supported with semantic search.
for_authorstring- Profile-curation audit view: an author ID (A…). Each result then carries this_authorship (the byline belonging to that author, with raw affiliations and raw ORCID, or the byline that best matches the author's name on works not yet attributed) plus coauthors; page 1 carries a summary of the profile. Typically used with author_ids=[same id] to list the profile's works, or with author_ids=[a duplicate profile] to review its works for merging.
from_yearinteger- Earliest publication year, inclusive (e.g. 2020).
funder_idsarray- OpenAlex funder IDs (e.g. F4320332161).
include_abstractsboolean- Include a truncated abstract per result. Default true.
include_retractedboolean- Include retracted works. Default false: retracted works are hidden and the response says so (retracted_works). Also honoured with oql, where the default leaves them out unless the query says otherwise (the echo then reads `it's not retracted`, or `non-retracted works` in the new form).
institution_idsarray- OpenAlex institution IDs (e.g. I27837315). Matches any author's affiliation.
is_traditionalboolean- true = only traditional scholarly works: the kinds the scholarly record has long counted (articles, books, chapters, theses, conference papers, preprints, reviews, editorials, letters...). false = only the rest (datasets, software, reports, abstracts, paratext...). Not the same as peer-reviewed: preprints and editorials are traditional.
keyword_idsarray- OpenAlex keyword ids (e.g. microplastics, human-health), any of them (OR). Find them with find_keywords. Keywords widen a text search; they do not replace it.
languagestring- ISO-639-1 language code, e.g. "en".
limitinteger- Results per page, 1-50. Default 15.
min_citationsinteger- Minimum cited_by_count. Not supported with semantic search.
modestring- Search mode. Default keyword.one of
keywordsemanticexact oa_statusarray- Only these open-access statuses (OR).
open_access_onlyboolean- Only works with a free-to-read copy.
oqlstring- An OQL query, e.g. works where title-abstract-keywords has ((vaping or "vape*" or "electronic cigarette*") and (youth or "adolescen*")) and published since 2018. A bare where-clause is accepted. Mutually exclusive with query and the structured filters.
pageinteger- Page number. Default 1.
previewboolean- Return only total_results, canonical OQL and a sample of preview_limit works (no abstracts). Use while tuning a query.
preview_limitinteger- Sample size for preview. Default 10.
preview_samplestring- Preview sample: top = highest-ranked (default); random = a random draw from the whole result set, better for judging precision.one of
toprandom publisher_idsarray- OpenAlex publisher IDs (e.g. P4310319908).
querystring- Search text. Keyword mode supports Boolean operators.
raw_filterstring- Escape hatch: extra OpenAlex filter expression appended verbatim, using the syntax documented at https://help.openalex.org/api/filtering/ (e.g. "has_abstract:true,primary_topic.field.id:17"). Combined with the structured filters above using AND.
rerankboolean- Relevance-sorted searches are reranked by default: the top 100 results are reordered by how well each work answers the query, so the first page holds the most on-topic works. Result 101 onward keeps the normal relevance order, and pages never repeat or skip a work. Costs twice a plain search. false = plain relevance order. Ignored for other sorts and semantic mode.
search_instring- Where keyword/exact queries match. title_abstract_keywords (default, what openalex.org searches) matches title and abstract text, and also works tagged with a keyword that a phrase in the query names (catches other wordings, other languages and works with no abstract; every other word must still be in the text); title_and_abstract matches the text only; fulltext also matches the body text of ~100M works, plus keywords (broader, more noise; large reviews that merely mention a term will rank high); title matches titles only. Ignored for semantic mode.one of
title_abstract_keywordstitle_and_abstractfulltexttitle sortstring- Sort order, descending. Default: relevance when there is a query, otherwise cited_by_count. Semantic mode takes relevance only.one of
relevancecited_by_countpublication_datefwci source_idsarray- OpenAlex source (journal/repository) IDs (e.g. S137773608).
to_yearinteger- Latest publication year, inclusive.
topic_idsarray- OpenAlex topic IDs (e.g. T10102), any of them (OR): works whose PRIMARY topic is one of these. Same meaning as OQL's `in the topic`, group_by topic and analyze_works top_topics. For works that carry the topic among any of their (up to 3) topics, use any_topic_ids.
typesarray- Only these work types (OR). Common: article, review, preprint, book-chapter, dataset.
openalexmcp_submit_curationsSubmit corrections to the user's claimed author profile as OpenAlex curations, up to 100 per call: add_work (attach a byline on a work to the profile), remove_work (detach the profile from a work), set_display_name, set_full_name (the name used to match future works), set_orcid, remove_orcid, and cancel (withdraw a pending curation).DestructiveSubmit profile corrections
Submit corrections to the user's claimed author profile as OpenAlex curations, up to 100 per call: add_work (attach a byline on a work to the profile), remove_work (detach the profile from a work), set_display_name, set_full_name (the name used to match future works), set_orcid, remove_orcid, and cancel (withdraw a pending curation). Every correction is reversible by the opposite action, even while the first is still pending (the newest correction for an item wins), and each item succeeds or fails on its own. Only submit what the user has agreed to: propose removes and adds with the evidence first, ask about anything that does not clearly fit. Adds are capped at 1,000 per rolling 24 hours. Curations apply on the nightly data refresh and are live within about two days; track them with list_my_curations. Do not re-check in minutes and conclude they failed.
- Idempotent
Inputs
itemsarrayrequired- No description.
author_idstring- The claimed profile (A…). Default: the account's claimed author.
No tools match.