OpenAlex MCP Server

Instructions

Implementation Reference

• src/tools/searchAuthors.ts:3-10 (handler)

  The handler function for the 'search_authors' tool. It makes a request to the OpenAlex /authors endpoint using the provided arguments and returns the JSON response formatted as MCP content.
  export async function searchAuthors(args: any) { return { content: [{ type: "text", text: JSON.stringify(await makeOpenAlexRequest("/authors", args), null, 2) }] }; }
• src/index.ts:78-98 (schema)

  The input schema and metadata definition for the 'search_authors' tool, provided in the ListTools response.
  { name: "search_authors", description: "Search authors and researchers", 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., 'orcid', 'last_known_institution.id'), IDs, and convenience filters (e.g., 'display_name.search'). Example: 'has_orcid:true,last_known_institution.country_code:US'" }, sort: { type: "string", description: "Sort field with optional :desc" }, page: { type: "number", description: "Page number" }, per_page: { type: "number", description: "Results per page (max 200)" }, cursor: { type: "string", description: "Cursor for deep pagination" }, group_by: { type: "string", description: "Group results by field" }, select: { type: "string", description: "Fields to return" }, sample: { type: "number", description: "Random sample size" }, seed: { type: "number", description: "Random seed" }, mailto: { type: "string", description: "Email for rate limits" }, api_key: { type: "string", description: "Premium API key" } } } },
• src/index.ts:283-284 (registration)

  The dispatch registration in the CallTool handler switch statement that maps 'search_authors' to the searchAuthors function.
  case "search_authors": return await searchAuthors(args);
• src/utils.ts:22-61 (helper)

  Shared utility function used by the search_authors handler to make HTTP requests to the OpenAlex API, handling query parameters, headers, authentication, and errors.
  export async function makeOpenAlexRequest(endpoint: string, params: OpenAlexQueryParams = {}): Promise<any> { const queryString = buildQueryString(params); const url = `${OPENALEX_BASE_URL}${endpoint}${queryString ? '?' + queryString : ''}`; try { // Build User-Agent with mailto for polite pool access let userAgent = 'OpenAlex-MCP-Server/1.0.0 (https://github.com/openalex-mcp-server)'; if (params.mailto) { userAgent += ` mailto:${params.mailto}`; } else { // Use environment variable for default email const defaultEmail = process.env.OPENALEX_DEFAULT_EMAIL || 'mcp-server@example.com'; userAgent += ` mailto:${defaultEmail}`; } // Build headers const headers: Record<string, string> = { 'Accept': 'application/json', 'User-Agent': userAgent }; // Add Bearer token - check parameter first, then environment variable const bearerToken = params.bearer_token || process.env.OPENALEX_BEARER_TOKEN; if (bearerToken) { headers['Authorization'] = `Bearer ${bearerToken}`; } const response = await axios.get(url, { headers, timeout: 30000 }); return response.data; } catch (error) { if (axios.isAxiosError(error)) { throw new Error(`OpenAlex API error: ${error.response?.status} - ${error.response?.statusText || error.message}`); } throw error; } }
• src/index.ts:23-23 (registration)

  Import statement that brings the searchAuthors handler into the main index file for registration.
  import { searchAuthors } from "./tools/searchAuthors.js";