OpenAlex MCP Server

Instructions

Implementation Reference

• src/tools/searchWorks.ts:4-41 (handler)

  The handler function that executes the 'search_works' tool. It queries the OpenAlex /works API endpoint, supports a 'summary' view by selecting specific fields and truncating large arrays (authorships to 5, concepts to 3), and returns JSON-formatted results wrapped in MCP content.
  export async function searchWorks(args: any) { const { view, ...searchArgs } = args; if (view === 'summary') { // Define the fields for the summary view searchArgs.select = 'id,doi,title,publication_year,type,cited_by_count,authorships,concepts,primary_location,open_access,best_oa_location'; const data = await makeOpenAlexRequest("/works", searchArgs); // Process the results to create the summary const summarizedResults = data.results.map((work: Work) => { // Limit authorships if (work.authorships && work.authorships.length > 5) { work.authorships = work.authorships.slice(0, 5); } // Limit concepts if (work.concepts && work.concepts.length > 3) { // Assuming concepts are sorted by score, which is typical. // If not, we might need to sort them first. work.concepts = work.concepts.slice(0, 3); } return work; }); return { content: [{ type: "text", text: JSON.stringify({ ...data, results: summarizedResults }, null, 2) }] }; } else { return { content: [{ type: "text", text: JSON.stringify(await makeOpenAlexRequest("/works", args), null, 2) }] }; } }
• src/index.ts:56-77 (schema)

  Input schema definition for the 'search_works' tool, specifying properties for search queries, filters, sorting, pagination, sampling, API keys, and the 'view' parameter for summary or full results.
  name: "search_works", description: "Search scholarly works in OpenAlex", inputSchema: { type: "object", properties: { search: { type: "string", description: "Full-text search query" }, filter: { type: "string", description: "Key:value OpenAlex filters. Supports entity attributes (e.g., 'publication_year', 'is_oa'), IDs, and convenience filters (e.g., 'title.search'). Example: 'is_oa:true,type:journal'" }, sort: { type: "string", description: "Sort field with optional :desc (e.g., 'cited_by_count:desc')" }, page: { type: "number", description: "Page number (max 10,000 results total)" }, per_page: { type: "number", description: "Results per page (max 200)" }, cursor: { type: "string", description: "Cursor for deep pagination (use '*' for first call)" }, group_by: { type: "string", description: "Group results by field for faceting" }, select: { type: "string", description: "Comma-separated list of fields to return" }, sample: { type: "number", description: "Random sample size" }, seed: { type: "number", description: "Random seed for reproducible sampling" }, mailto: { type: "string", description: "Email for rate limits" }, api_key: { type: "string", description: "Premium API key" }, bearer_token: { type: "string", description: "Bearer token for authentication" }, view: { type: "string", "enum": ["summary", "full"], description: "The view of the data to return. 'summary' returns a concise version, 'full' returns the complete object." } } } },
• src/index.ts:281-282 (registration)

  Dispatches calls to the 'search_works' tool by invoking the imported searchWorks handler function in the CallToolRequest handler switch statement.
  case "search_works": return await searchWorks(args);
• src/index.ts:22-22 (registration)

  Imports the searchWorks handler function from the tools directory for use in tool dispatch.
  import { searchWorks } from "./tools/searchWorks.js";