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

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

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.