PBS API MCP server

This MCP server provides access to the Australian Pharmaceutical Benefits Scheme (PBS) API, allowing AI models to retrieve information about medicines, pricing, and availability in Australia. It serves as a bridge between AI systems and Australia's pharmaceutical database.

Installation

To install the PBS MCP server:

1. Clone the repository:

   git clone <repository-url>
   cd pbs-mcp-standalone
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Running the Server

The server can be run in different modes:

Stdio Mode (Default)

This mode communicates via standard input/output streams:

npm start

Or use the provided script:

./start.sh

HTTP Mode with SSE Support

Start an HTTP server with Server-Sent Events support:

npm run start:http

Or specify a port:

./start.sh http 3000

Command-Line Interface

The server can also be used as a command-line tool:

npm run cli -- <command>

Or:

./start.sh cli <command>

Example:

./start.sh cli info

Authentication

The tool uses a subscription key for accessing the PBS API. To obtain your own key:

1. Visit the PBS Data API Portal
2. Create an account and verify your email
3. Subscribe to the "PBS Public API v3" product
4. Retrieve your subscription key from your profile
5. Create a .env file based on .env.example with your key:

   PBS_API_SUBSCRIPTION_KEY=your-actual-subscription-key
   

Note: The PBS Public API is rate-limited to one request per 20 seconds.

Using the API Tools

API Tool Parameters

{
  "endpoint": "prescribers",
  "method": "GET",
  "params": {
    "get_latest_schedule_only": "true",
    "limit": "20"
  }
}

Parameters

• endpoint (string, required): The PBS API endpoint to access
• method (string, optional): HTTP method (default: "GET")
• params (object, optional): Query parameters for the request
• subscriptionKey (string, optional): Custom subscription key
• timeout (number, optional): Request timeout in milliseconds (default: 30000)

Example Requests

Get API Information

{
  "endpoint": ""
}

Get Prescribers

{
  "endpoint": "prescribers",
  "params": {
    "get_latest_schedule_only": "true",
    "limit": "10"
  }
}

Get Item Overview

{
  "endpoint": "item-overview",
  "params": {
    "get_latest_schedule_only": "true",
    "limit": "5"
  }
}

Get Prescribers with Specific PBS Code

{
  "endpoint": "prescribers",
  "params": {
    "pbs_code": "10001J",
    "get_latest_schedule_only": "true"
  }
}

Command-Line Interface

The PBS MCP server offers several CLI commands:

List Endpoints

./start.sh cli list-endpoints

Get API Information

./start.sh cli info

Query Prescribers

./start.sh cli prescribers [options]

Options:

• -l, --limit <number>: Results per page (default: 10)
• -p, --page <number>: Page number (default: 1)
• -c, --pbs-code <code>: Filter by PBS code
• -s, --schedule-code <code>: Filter by schedule code
• -t, --prescriber-type <type>: Filter by prescriber type
• -f, --fields <fields>: Specific fields to return
• --latest: Get only the latest schedule

Query Item Overview

./start.sh cli item-overview [options]

Options:

• -l, --limit <number>: Results per page (default: 10)
• -p, --page <number>: Page number (default: 1)
• -s, --schedule-code <code>: Filter by schedule code
• -f, --fields <fields>: Specific fields to return
• --latest: Get only the latest schedule

Query Any Endpoint

./start.sh cli query <endpoint> [options]

Options:

• -m, --method <method>: HTTP method (default: GET)
• -p, --params <json>: Query parameters as JSON string
• -k, --subscription-key <key>: Custom subscription key
• -t, --timeout <milliseconds>: Request timeout

Start HTTP Server

./start.sh cli serve [options]

Options:

• -p, --port <number>: Port to listen on (default: 3000)

HTTP API

When running in HTTP mode, these endpoints are available:

• GET /health: Server status
• GET /tools: List available tools
• GET /sse: Establish SSE connection
• POST /sse/:toolName: Invoke tool via SSE
• POST /api/:toolName: Invoke tool via REST

Available PBS Endpoints

The PBS API provides several endpoints:

• / - API information and changelog
• /prescribers - Information about prescribers
• /item-overview - Detailed PBS item information
• /items - Basic PBS item information
• /schedules - PBS schedules information
• /atc-codes - ATC classification codes
• /organisations - Organisation information
• /restrictions - Restriction information
• /parameters - Parameter information
• /criteria - Criteria information
• /copayments - Copayment information
• /fees - Fee information
• /markup-bands - Markup band information
• /programs - Program information
• /summary-of-changes - Summary of changes

Integrating with MCP Clients

This server can be integrated with any MCP-compatible client:

{
  "mcpServers": {
    "pbs-api": {
      "command": "node",
      "args": ["path/to/pbs-mcp-standalone/build/index.js"],
      "env": {
        "PBS_API_SUBSCRIPTION_KEY": "your-subscription-key-here"
      }
    }
  }
}

Example LLM Prompts

The server can interpret natural language prompts such as:

• "Find information about metformin in the PBS"
• "What is the PBS code for insulin?"
• "List all prescribers who can prescribe antibiotics"
• "Get the latest pricing for asthma medications"

Limitations

• The PBS Public API is rate-limited to one request per 20 seconds
• Only the current schedule and those from the past 12 months are available
• Some endpoints require specific parameters
• The API structure may change over time

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "pbs-api" '{"command":"node","args":["path/to/pbs-mcp-standalone/build/index.js"],"env":{"PBS_API_SUBSCRIPTION_KEY":"your-subscription-key-here"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "pbs-api": {
            "command": "node",
            "args": [
                "path/to/pbs-mcp-standalone/build/index.js"
            ],
            "env": {
                "PBS_API_SUBSCRIPTION_KEY": "your-subscription-key-here"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "pbs-api": {
            "command": "node",
            "args": [
                "path/to/pbs-mcp-standalone/build/index.js"
            ],
            "env": {
                "PBS_API_SUBSCRIPTION_KEY": "your-subscription-key-here"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect