openfda-mcp-server by prahlaadr - MCP Server

OpenFDA MCP Server

A Model Context Protocol (MCP) server that provides access to FDA device classification data through the OpenFDA API.

Features

🔍 Search FDA device classifications by name, class, or medical specialty
⚡ Fast, async API calls with proper error handling
📊 Configurable result limits (1-1000 results)
🛡️ Comprehensive input validation and sanitization
📝 Structured, readable output format
🔄 Automatic retry logic for network issues
📋 Extensive logging and monitoring

Quick Start

Installation

Option 1: Direct Installation with pipx (Recommended)

pipx install git+https://github.com/prahlaadr/openfda-mcp-server.git

Option 2: Development Installation

# Clone the repository
git clone https://github.com/prahlaadr/openfda-mcp-server.git
cd openfda-mcp-server

# Install in development mode
pip install -e .

Running the Server

# Using the installed command
openfda-mcp-server

# Or directly with Python
python -m openfda_mcp_server.run_server

Claude Desktop Configuration

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

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "openfda": {
      "command": "/Users/yourusername/.local/pipx/venvs/openfda-mcp-server/bin/python",
      "args": ["-m", "openfda_mcp_server.run_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Note: Replace /Users/yourusername/ with your actual home directory path.

Alternative Configuration (Direct Command)

{
  "mcpServers": {
    "openfda": {
      "command": "openfda-mcp-server",
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

After configuration, restart Claude Desktop and you can ask questions like:

"Search for cardiac medical devices"
"Find Class II surgical instruments"
"What are the FDA classifications for stethoscopes?"

Available Tools

search_device_classifications

Search FDA device classifications with flexible query options.

Parameters:

search (optional): Search query string for device names, classifications, or medical specialties
limit (optional): Number of results to return (1-1000, default: 10)

Examples:

// Search for stethoscopes
{"search": "stethoscope", "limit": 5}

// Get latest 20 classifications
{"limit": 20}

// Search for cardiac devices
{"search": "cardiac"}

Response Format:

The tool returns formatted markdown with:

Device name and classification
Medical specialty
Regulation number
Product code
Total results count

Development

Running Tests

# Run all tests
python -m pytest test_*.py -v

# Run specific test file
python -m pytest test_integration.py -v

# Run with coverage
python -m pytest test_*.py --cov=openfda_mcp_server

Project Structure

openfda-mcp-server/
├── .github/workflows/       # CI/CD pipeline
├── openfda_mcp_server/      # Main package
│   ├── __init__.py
│   ├── config.py           # Configuration management
│   ├── main.py            # MCP server implementation
│   └── run_server.py      # Entry point
├── test_basic.py          # Core functionality tests
├── test_errors.py         # Error handling tests
├── test_integration.py    # API integration tests
├── requirements.txt       # Dependencies
├── setup.py              # Package setup
└── README.md             # This file

API Information

This server uses the OpenFDA Device Classification API:

Endpoint: https://api.fda.gov/device/classification.json
Documentation: https://open.fda.gov/apis/device/classification/
Rate Limits: 240 requests per minute (per IP)
Total Records: 6,978+ device classifications available

Error Handling

The server includes comprehensive error handling for:

❌ Network connectivity issues
⏱️ API rate limiting (with helpful retry messages)
🔍 Invalid search parameters
🚫 API server errors (500+ status codes)
📝 Malformed API responses
🔄 Automatic retry logic for transient failures

Configuration

Environment Variables

LOG_LEVEL: Set logging verbosity (DEBUG, INFO, WARNING, ERROR)
```
export LOG_LEVEL=DEBUG
openfda-mcp-server
```

Logs

The server creates logs in:

macOS: ~/Library/Logs/openfda_mcp.log
Console: Real-time output via stderr

Troubleshooting

Claude Desktop Connection Issues

Verify Installation:

which openfda-mcp-server
openfda-mcp-server  # Should start without errors

Check Configuration:

python3 -m json.tool "~/Library/Application Support/Claude/claude_desktop_config.json"

View Logs:
```
tail -f ~/Library/Logs/openfda_mcp.log
```
Restart Claude Desktop after configuration changes

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Install development dependencies
pip install -r requirements.txt

# Run tests before committing
python -m pytest test_*.py -v

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

Built for the Model Context Protocol
Powered by OpenFDA API
Inspired by the need for accessible FDA device data

Support

Made with ❤️ for the MCP community