OpenAlex MCP Server

Instructions

Implementation Reference

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

  The core handler function for the 'search_topics' tool. It calls makeOpenAlexRequest on the '/topics' endpoint with input args and returns the JSON response formatted as MCP text content.

  export async function searchTopics(args: any) {
      return {
          content: [{
                  type: "text",
                  text: JSON.stringify(await makeOpenAlexRequest("/topics", args), null, 2)
              }]
      };
  }

• src/index.ts:141-161 (schema)

  Input schema for the 'search_topics' tool as defined in the ListTools handler response.

  {
      name: "search_topics",
      description: "Search research topics (formerly concepts)",
      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., 'domain.id', 'level'), IDs, and convenience filters (e.g., 'display_name.search'). Example: 'domain.id:D1,level:0'" },
              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:289-290 (registration)

  Registration in the CallToolRequest switch statement that dispatches to the searchTopics handler.

  case "search_topics":
      return await searchTopics(args);