Unpaywall MCP Server

Instructions

Implementation Reference

• src/index.ts:246-274 (handler)

  Executes the unpaywall_get_fulltext_links tool: validates args, normalizes DOI, fetches Unpaywall data, extracts best PDF/open URLs and metadata.

  if (tool === TOOL_GET_FULLTEXT_LINKS) {
    const args = (req.params.arguments ?? {}) as Partial<GetByDoiArgs>;
    const rawDoi = (args.doi ?? "").toString().trim();
    if (!rawDoi) {
      return { content: [{ type: "text", text: "Missing required argument: 'doi'" }], isError: true };
    }
    const email = (args.email || process.env.UNPAYWALL_EMAIL || "").toString().trim();
    if (!email) {
      return { content: [{ type: "text", text: "Unpaywall requires an email. Set UNPAYWALL_EMAIL or pass 'email'." }], isError: true };
    }
    const doi = normalizeDoi(rawDoi);
    const obj = await fetchUnpaywallByDoi(doi, email);
    const best = obj?.best_oa_location ?? null;
    const locations: any[] = Array.isArray(obj?.oa_locations) ? obj.oa_locations : [];
    const pickPdfFrom = (locs: any[]) => locs.find(l => l?.url_for_pdf) || locs.find(l => l?.url);
    const bestPdfUrl = best?.url_for_pdf || best?.url || (pickPdfFrom(locations)?.url_for_pdf || pickPdfFrom(locations)?.url) || null;
    const bestOpenUrl = best?.url || (locations.find(l => l?.url)?.url) || null;
    const result = {
      doi: obj?.doi ?? doi,
      title: obj?.title ?? null,
      is_oa: obj?.is_oa ?? null,
      oa_status: obj?.oa_status ?? null,
      best_pdf_url: bestPdfUrl,
      best_open_url: bestOpenUrl,
      best_oa_location: best,
      oa_locations: locations,
    };
    return { content: [{ type: "json", json: result }] };
  }

• src/index.ts:165-177 (schema)

  Input schema definition for the unpaywall_get_fulltext_links tool, registered in ListTools response.

  {
    name: TOOL_GET_FULLTEXT_LINKS,
    description: "Given a DOI, return best open-access links (best PDF URL and open URL) plus Unpaywall locations metadata.",
    inputSchema: {
      type: "object",
      properties: {
        doi: { type: "string", description: "DOI string or DOI URL" },
        email: { type: "string", description: "Email to identify your requests to Unpaywall (optional override)" },
      },
      required: ["doi"],
      additionalProperties: false,
    },
  },

• src/index.ts:133-195 (registration)

  Registration of all tools including unpaywall_get_fulltext_links in the ListToolsRequestHandler.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: TOOL_GET_BY_DOI,
          description:
            "Fetch Unpaywall metadata for a DOI (accepts DOI, DOI URL, or 'doi:' prefix). Requires an email address via env UNPAYWALL_EMAIL or the optional 'email' argument.",
          inputSchema: {
            type: "object",
            properties: {
              doi: { type: "string", description: "DOI string or DOI URL, e.g. 10.1038/nphys1170 or https://doi.org/10.1038/nphys1170" },
              email: { type: "string", description: "Email to identify your requests to Unpaywall (optional override)" },
            },
            required: ["doi"],
            additionalProperties: false,
          },
        },
        {
          name: TOOL_SEARCH_TITLES,
          description: "Search Unpaywall for article titles matching a query. Supports optional is_oa filter and pagination (50 results per page).",
          inputSchema: {
            type: "object",
            properties: {
              query: { type: "string", description: "Title search query (supports phrase, boolean operators per Unpaywall docs)" },
              is_oa: { type: "boolean", description: "If true, only return OA results; if false, only closed; omit for all" },
              page: { type: "integer", minimum: 1, description: "Page number (50 results per page)" },
              email: { type: "string", description: "Email to identify your requests to Unpaywall (optional override)" },
            },
            required: ["query"],
            additionalProperties: false,
          },
        },
        {
          name: TOOL_GET_FULLTEXT_LINKS,
          description: "Given a DOI, return best open-access links (best PDF URL and open URL) plus Unpaywall locations metadata.",
          inputSchema: {
            type: "object",
            properties: {
              doi: { type: "string", description: "DOI string or DOI URL" },
              email: { type: "string", description: "Email to identify your requests to Unpaywall (optional override)" },
            },
            required: ["doi"],
            additionalProperties: false,
          },
        },
        {
          name: TOOL_FETCH_PDF_TEXT,
          description: "Download and extract text from best OA PDF for a DOI, or from a provided PDF URL.",
          inputSchema: {
            type: "object",
            properties: {
              doi: { type: "string", description: "DOI string or DOI URL. Used if pdf_url is not provided." },
              pdf_url: { type: "string", description: "Direct PDF URL to download and parse (takes precedence over DOI)." },
              email: { type: "string", description: "Email to identify requests to Unpaywall (required when resolving via DOI)." },
              truncate_chars: { type: "integer", minimum: 1000, description: "Max characters of extracted text to return (default 20000)." },
            },
            required: [],
            additionalProperties: false,
          },
        },
      ],
    };
  });

• src/index.ts:47-61 (helper)

  Helper function to fetch Unpaywall metadata by DOI, used by the tool handler.

  async function fetchUnpaywallByDoi(doi: string, email: string) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), 20_000);
    try {
      const url = `https://api.unpaywall.org/v2/${encodeURIComponent(doi)}?email=${encodeURIComponent(email)}`;
      const resp = await fetch(url, { signal: controller.signal, headers: { "Accept": "application/json" } });
      if (!resp.ok) {
        const text = await resp.text().catch(() => "");
        throw new Error(`Unpaywall HTTP ${resp.status}: ${text.slice(0, 400)}`);
      }
      return await resp.json();
    } finally {
      clearTimeout(timeout);
    }
  }

• src/index.ts:38-45 (helper)

  Helper function to normalize DOI input by stripping prefixes.

  function normalizeDoi(input: string): string {
    let doi = input.trim();
    // Strip common DOI URL prefixes
    doi = doi.replace(/^https?:\/\/(dx\.)?doi\.org\//i, "");
    // Strip leading 'doi:' prefix
    doi = doi.replace(/^doi:/i, "");
    return doi.trim();
  }