Skip to main content
Glama
NIH RePORTER MCP Server

NIH RePORTER MCP Server

by rdwj

NIH RePORTER MCP Server

An MCP server that wraps the NIH RePORTER API v2, enabling AI agents to search and analyze NIH-funded research projects and their linked publications. No API key required.

Tools

Tool

Description

nih_search_projects

Search for NIH research projects by text, PI, organization, funding, and more

nih_get_project

Get full details for a specific project by application ID or project number

nih_find_publications

Find PubMed publications linked to NIH grants

nih_search_projects

Search the NIH RePORTER database for federally funded research projects. Multiple criteria are combined with AND logic; within list parameters, values use OR logic.

Parameters:

  • text (string, optional): Free-text search across titles, abstracts, and terms

  • text_operator ("and" | "or", default "and"): How multi-word queries are combined

  • text_fields ("all" | "title" | "abstract" | "terms", default "all"): Which fields to search

  • pi_name (string, optional): PI name, e.g. "Smith, John" or "Smith"

  • organization (string, optional): Organization name (partial match)

  • activity_codes (list of string, optional): e.g. ["R01", "R21"]

  • agencies (list of string, optional): NIH IC abbreviations, e.g. ["NCI", "NIMH"]

  • fiscal_years (list of int, optional): e.g. [2024, 2025]

  • funding_mechanism (list of string, optional): e.g. ["RP", "SB"]

  • spending_categories (list of int, optional): RCDC category IDs

  • states (list of string, optional): US state abbreviations

  • award_amount_min / award_amount_max (int, optional): Dollar range

  • project_start_after / project_start_before (string, optional): YYYY-MM-DD

  • exclude_subprojects (bool, default true): Exclude subprojects

  • include_active_only (bool, default false): Only active projects

  • detail_level ("summary" | "full", default "summary"): Summary returns key fields; full includes abstracts

  • sort_by ("relevance" | "date" | "amount", default "relevance"): Sort order

  • limit (int, default 10, max 50): Results per page

  • offset (int, default 0): Pagination offset

  • search_id (string, optional): Reuse a prior search for pagination

Example:

{
  "text": "machine learning",
  "agencies": ["NIGMS"],
  "activity_codes": ["R01"],
  "fiscal_years": [2025],
  "limit": 5
}

nih_get_project

Get full details for a specific NIH-funded project. Use after finding a project of interest via nih_search_projects.

Parameters:

  • appl_id (int, optional): Application ID, e.g. 10878415

  • project_num (string, optional): Full project number, e.g. "5R01CA123456-03"

One of appl_id or project_num is required.

Example:

{"appl_id": 10878415}

nih_find_publications

Find PubMed publications linked to NIH-funded projects. Returns PMIDs that can be used with PubMed APIs for full citation details.

Parameters:

  • core_project_nums (list of string, optional): e.g. ["R01CA123456"]. Supports wildcard *.

  • appl_ids (list of int, optional): Application IDs

  • pmids (list of int, optional): PubMed IDs (reverse lookup: which grants funded this paper?)

  • limit (int, default 50, max 500): Results per page

  • offset (int, default 0): Pagination offset

At least one of the search parameters is required.

Example:

{"core_project_nums": ["R01CA123456"]}

Related MCP server: NIH Reporter MCP Server

Quick Start

Local Development

make install
make run-local

# Test with cmcp (in another terminal)
cmcp ".venv/bin/python -m src.main" tools/list

Deploy to OpenShift

make deploy PROJECT=my-project

Client Configuration

STDIO (local):

{
  "mcpServers": {
    "nih-reporter": {
      "command": ".venv/bin/python",
      "args": ["-m", "src.main"]
    }
  }
}

HTTP (remote):

{
  "mcpServers": {
    "nih-reporter": {
      "url": "https://<route>/mcp/"
    }
  }
}

Development

Running Tests

make test

# Or directly
.venv/bin/pytest tests/ -v

# Single test file
.venv/bin/pytest tests/tools/test_nih_search_projects.py -v

Adding Tools

Create a Python file in src/tools/ using the @mcp.tool decorator:

from typing import Annotated
from pydantic import Field
from fastmcp import Context
from fastmcp.exceptions import ToolError
from src.core.app import mcp

@mcp.tool(
    annotations={"readOnlyHint": True, "openWorldHint": True},
    timeout=30.0,
)
async def my_tool(
    param: Annotated[str, Field(description="Parameter description")],
    ctx: Context = None,
) -> dict:
    """Tool description for the LLM."""
    return {"result": param}

Generate scaffolds with:

fips-agents generate tool my_tool --description "Tool description" --async --with-context

Project Structure

src/
├── core/
│   ├── app.py          # Shared FastMCP instance
│   ├── server.py       # Server bootstrap (load + run)
│   ├── loaders.py      # Dynamic component discovery
│   ├── auth.py         # Optional JWT authentication
│   └── logging.py      # Logging configuration
├── tools/
│   ├── nih_client.py          # Shared HTTP client with rate limiting
│   ├── nih_search_projects.py # Project search tool
│   ├── nih_get_project.py     # Project detail tool
│   └── nih_find_publications.py # Publication search tool
├── resources/          # (none currently)
├── prompts/            # (none currently)
└── middleware/         # (none currently)
tests/
└── tools/
    ├── test_nih_search_projects.py  # 55 tests
    ├── test_nih_get_project.py      # 8 tests
    └── test_nih_find_publications.py # 9 tests

Dependencies

  • fastmcp >= 2.11.3 -- MCP server framework

  • httpx >= 0.28.0 -- Async HTTP client for NIH API calls

Environment Variables

Variable

Default

Purpose

MCP_TRANSPORT

stdio

Transport: stdio or http

MCP_HTTP_HOST

127.0.0.1

HTTP bind address

MCP_HTTP_PORT

8000

HTTP port

MCP_HTTP_PATH

/mcp/

HTTP endpoint path

MCP_LOG_LEVEL

INFO

Logging level

MCP_HOT_RELOAD

0

Enable hot-reload for development

MCP_SERVER_NAME

fastmcp-unified

Server name in MCP responses

NIH API Notes

  • No authentication required. The API is publicly accessible.

  • Rate limit: 1 request per second (enforced by the shared client).

  • Result limit: The API can return at most 15,000 records per search. The tool warns when this limit is hit.

  • Documentation: api.reporter.nih.gov

License

This project is licensed under the MIT License.

Available Tools

3 tools
nih_find_publicationsNih Find PublicationsA
Read-only

Find publications linked to NIH-funded projects.

Returns PubMed IDs (PMIDs) associated with grants. Search by core project number (e.g. 'R01CA123456', supports wildcard *), application ID, or PubMed ID. Use PMIDs with PubMed APIs for full citation details. Note: publication linkage may lag behind award dates.

Inputs: limit, pmids, offset, appl_ids, +1 more. Returns: object

nih_get_projectNih Get ProjectA
Read-only

Get full details for a specific NIH-funded project.

Use this after finding a project of interest via nih_search_projects. Accepts either an application ID (numeric, e.g. 10878415) or a full project number (e.g. '5R01CA123456-03'). Returns the complete record including abstract, all PIs, funding breakdown, and study section.

Inputs: appl_id, project_num. Returns: object

nih_search_projectsNih Search ProjectsA
Read-only

Search the NIH RePORTER database for federally funded research projects.

NIH RePORTER (Research Portfolio Online Reporting Tools) provides access to data on all research projects funded by the National Institutes of Health. This includes grants, contracts, and intramural projects across all 27 NIH institutes and centers.

Text search supports multi-word queries. With text_operator="and" (default), all words must appear in the searched fields. With "or", any word matching is sufficient. Wrap phrases in quotes for exact phrase matching within the text parameter.

Multiple criteria are combined with AND logic (e.g., text + agency narrows results to projects matching both). Within list parameters like agencies or activity_codes, values use OR logic.

Common activity codes: R01 - Research Project Grant (most common) R21 - Exploratory/Developmental Research R03 - Small Research Grant P01 - Program Project Grant U01 - Research Project Cooperative Agreement K01 - Mentored Research Scientist Career Development K08 - Mentored Clinical Scientist Career Development K23 - Mentored Patient-Oriented Research Career Development T32 - Institutional Training Grant F31 - Predoctoral Fellowship F32 - Postdoctoral Fellowship

Common agency abbreviations: NCI (Cancer), NIMH (Mental Health), NIGMS (General Medical Sciences), NIAID (Allergy/Infectious Diseases), NHLBI (Heart/Lung/Blood), NIA (Aging), NINDS (Neurological Disorders), NIDA (Drug Abuse), NICHD (Child Health), NIDDK (Diabetes/Digestive/Kidney)

Inputs: text, limit, offset, states, +18 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 3 tools

    Disambiguation5/5

    The three tools have clearly distinct purposes: searching for projects, retrieving full project details, and finding linked publications. Each tool's description clarifies its specific role, leaving no ambiguity for an agent to choose the appropriate tool.

    Naming Consistency5/5

    All tool names follow a consistent snake_case convention with a common 'nih_' prefix and verb_noun structure: nih_search_projects, nih_get_project, nih_find_publications. This pattern is predictable and easy to parse.

    Tool Count5/5

    With only 3 tools, the set is minimal but well-scoped for the core read-only operations of the NIH RePORTER database. Each tool serves a distinct essential function without overlap or redundancy.

    Completeness4/5

    The tools cover the primary read operations: search, detail retrieval, and publication linkage. However, there is no support for listing related entities (e.g., all projects by a PI or organization) or exporting results, which could be useful but are not critical for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides programmatic access to the NIH Reporter API for searching and retrieving detailed information on NIH-funded research projects, grants, and investigators. It enables AI assistants to query project abstracts, funding amounts, and organization details through natural language.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search and retrieve EU research outputs including publications, datasets, software, and funded projects from OpenAIRE.
      85 npm
      MIT