NIH Reporter MCP Server

A Model Context Protocol (MCP) server that provides programmatic access to the NIH Reporter API for searching and retrieving information about NIH-funded research projects.

Overview

This MCP server allows AI assistants and other MCP clients to search for and retrieve detailed information about NIH-funded research grants, including:

Project details and funding information
Principal investigator information
Organization details
Project abstracts and public health relevance
Award amounts and dates
Study sections and review information

Features

Available Tools

search_projects - Search for NIH projects using multiple criteria:
- Fiscal years
- NIH Institutes/Centers (IC codes)
- Activity codes (R01, P01, etc.)
- Organization names
- Principal investigator names
- Project numbers
- Award amount ranges
- Date ranges
- Keywords in title/abstract
get_project_details - Get comprehensive details about a specific project by project number or application ID
search_recent_awards - Find recently awarded projects within a specified number of days
search_by_investigator - Search for all projects by a specific principal investigator
get_spending_categories - Get information about NIH spending categories

Prerequisites

Docker and Docker Compose installed
Basic understanding of MCP (Model Context Protocol)

Quick Start

1. Build the Docker Image

docker-compose build

2. Run the Server

docker-compose up

The server will start and listen for MCP requests via stdin/stdout.

3. Alternative: Build and Run with Docker Only

# Build the image
docker build -t nih-reporter-mcp .

# Run the container
docker run -i nih-reporter-mcp

Configuration for Claude Desktop

To use this MCP server with Claude Desktop, add it to your Claude configuration file:

On macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json

On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nih-reporter": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "nih-reporter-mcp"]
    }
  }
}

After adding this configuration, restart Claude Desktop.

Usage Examples

Once connected to an MCP client (like Claude Desktop), you can use natural language to interact with the NIH Reporter API:

Example 1: Search for Recent Cancer Research

"Find recent NIH cancer research projects from the National Cancer Institute awarded in 2025"

This will use the search_projects tool with:

agencies: ["NCI"]
fiscal_years: [2025]

Example 2: Find Projects by Investigator

"Show me all NIH projects where John Smith is the principal investigator"

This will use the search_by_investigator tool.

Example 3: Get Project Details

"Get detailed information about project R01CA123456"

This will use the get_project_details tool.

Example 4: Search Recent Awards

"What are the newest NIH awards from the last 7 days?"

This will use the search_recent_awards tool.

Using with Azure OpenAI Responses API

You can integrate this MCP server with Azure OpenAI's Responses API using function calling. Here are snippets showing how to define the tools in different languages:

Python

from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# Configure Azure AD authentication
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default"
)

client = AzureOpenAI(
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    azure_ad_token_provider=token_provider,
    api_version="preview"
)

# Define NIH Reporter search tool
tools = [
    {
        "type": "function",
        "function": {
            "name": "search_projects",
            "description": "Search for NIH-funded research projects using multiple criteria including fiscal years, agencies, activity codes, and keywords",
            "parameters": {
                "type": "object",
                "properties": {
                    "fiscal_years": {
                        "type": "array",
                        "items": {"type": "integer"},
                        "description": "Fiscal years to search (e.g., [2024, 2025])"
                    },
                    "agencies": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "NIH Institute/Center codes (e.g., ['NCI', 'NHLBI'])"
                    },
                    "activity_codes": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Grant activity codes (e.g., ['R01', 'K99'])"
                    },
                    "pi_names": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Principal investigator names"
                    },
                    "keywords": {
                        "type": "string",
                        "description": "Search keywords for project titles/abstracts"
                    }
                }
            }
        }
    }
]

response = client.responses.create(
    model="gpt-4.1",
    tools=tools,
    input="What recent NIH projects were targeted at early career researchers?"
)

print(response.output_text)

C#

using Azure.AI.OpenAI;
using Azure.Identity;

var credential = new DefaultAzureCredential();
var client = new AzureOpenAIClient(
    new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/"),
    credential
);

var tools = new[]
{
    new
    {
        type = "function",
        function = new
        {
            name = "search_projects",
            description = "Search for NIH-funded research projects using multiple criteria",
            parameters = new
            {
                type = "object",
                properties = new
                {
                    fiscal_years = new
                    {
                        type = "array",
                        items = new { type = "integer" },
                        description = "Fiscal years to search (e.g., [2024, 2025])"
                    },
                    agencies = new
                    {
                        type = "array",
                        items = new { type = "string" },
                        description = "NIH Institute/Center codes (e.g., ['NCI', 'NHLBI'])"
                    },
                    activity_codes = new
                    {
                        type = "array",
                        items = new { type = "string" },
                        description = "Grant activity codes (e.g., ['R01', 'K99'])"
                    },
                    keywords = new
                    {
                        type = "string",
                        description = "Search keywords for project titles/abstracts"
                    }
                }
            }
        }
    }
};

var response = await client.GetResponsesClient("gpt-4.1").CreateAsync(new()
{
    Tools = tools,
    Input = "What recent NIH projects were targeted at early career researchers?"
});

Console.WriteLine(response.Value.OutputText);

PHP

<?php
require 'vendor/autoload.php';

use OpenAI\Azure\Client;

$client = Client::factory()
    ->withBaseUri('https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/')
    ->withAzureAdToken(getAzureAdToken())
    ->withApiVersion('preview')
    ->make();

$tools = [
    [
        'type' => 'function',
        'function' => [
            'name' => 'search_projects',
            'description' => 'Search for NIH-funded research projects using multiple criteria',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'fiscal_years' => [
                        'type' => 'array',
                        'items' => ['type' => 'integer'],
                        'description' => 'Fiscal years to search'
                    ],
                    'agencies' => [
                        'type' => 'array',
                        'items' => ['type' => 'string'],
                        'description' => 'NIH Institute/Center codes'
                    ],
                    'activity_codes' => [
                        'type' => 'array',
                        'items' => ['type' => 'string'],
                        'description' => 'Grant activity codes'
                    ],
                    'keywords' => [
                        'type' => 'string',
                        'description' => 'Search keywords'
                    ]
                ]
            ]
        ]
    ]
];

$response = $client->responses()->create([
    'model' => 'gpt-4.1',
    'tools' => $tools,
    'input' => 'What recent NIH projects were targeted at early career researchers?'
]);

echo $response['output_text'];
?>

Integration Notes:

To connect these tools to your MCP server backend:

Start the Docker container: docker run -i --rm nih-reporter-mcp
When Azure OpenAI calls your function, intercept the function call
Send the corresponding MCP protocol message via stdin to the Docker container
Parse the JSON-RPC response from stdout
Return the results to Azure OpenAI to generate the final response

Available Tools:

search_projects - Search with multiple criteria
get_project_details - Get details by project number
search_recent_awards - Find recent awards by days
search_by_investigator - Search by PI name
get_spending_categories - Get NIH spending categories

API Reference

NIH Institute/Center Codes

Common IC codes you can use in searches:

NCI - National Cancer Institute
NIDA - National Institute on Drug Abuse
NHLBI - National Heart, Lung, and Blood Institute
NIAID - National Institute of Allergy and Infectious Diseases
NIMH - National Institute of Mental Health
NIA - National Institute on Aging
NICHD - National Institute of Child Health and Human Development
NIDDK - National Institute of Diabetes and Digestive and Kidney Diseases

See the documentation PDFs for the complete list.

Common Activity Codes

R01 - Research Project Grant
R21 - Exploratory/Developmental Research Grant
R03 - Small Research Grant
P01 - Research Program Project Grant
U01 - Research Project Cooperative Agreement
K01-K99 - Career Development Awards
T32 - Institutional Training Grant
F31-F33 - Individual Predoctoral/Postdoctoral Fellowship

Development

Project Structure

.
├── server.py           # Main MCP server implementation
├── requirements.txt    # Python dependencies
├── Dockerfile         # Docker container definition
├── docker-compose.yml # Docker Compose configuration
├── README.md          # This file
└── [PDF documentation files]

Local Development (Without Docker)

Install dependencies:

pip install -r requirements.txt

Run the server:

python server.py

Modifying the Server

The server code is in server.py. Key sections:

Tool definitions: list_tools() function
Tool handlers: Individual async functions for each tool
API integration: make_nih_api_request() function

After making changes, rebuild the Docker image:

docker-compose build

Troubleshooting

Server Not Responding

Check if the container is running:

docker ps

View logs:

docker-compose logs -f

API Errors

The NIH Reporter API may occasionally be slow or unavailable. The server includes a 30-second timeout for API requests.

Connection Issues

Ensure that:

Docker is running
The container has internet access to reach api.reporter.nih.gov
No firewall is blocking outbound HTTPS connections

Data Sources

This server uses the NIH Reporter API v2:

API Base URL: https://api.reporter.nih.gov/v2
Documentation: Included PDF files in this directory

Limitations

Maximum 500 results per query (API limitation)
30-second timeout per API request
Rate limiting may apply (enforced by NIH Reporter API)

License

This MCP server implementation is provided as-is for use with the NIH Reporter public API.

Contributing

Contributions are welcome! Please ensure:

Code follows Python best practices
All tools are properly documented
Docker container builds successfully
README is updated for new features

Support

For issues related to:

This MCP server: Check logs and troubleshooting section
NIH Reporter API: See official NIH Reporter documentation
MCP Protocol: See Model Context Protocol documentation

Version

Current Version: 1.0.0

Credits

Built using:

MCP SDK for Python
NIH Reporter API v2
Docker for containerization