Skip to main content

npreq-mcp: the NPReq API as MCP tools

NPReq gives nurse practitioners and the tools they use curated NP/APRN state requirement data for 56 US jurisdictions: practice authority, licensure, continuing education (CE) rules, renewal, prescribing and board contacts, each value with the official source it came from. This repository holds two things:

  • npreq-mcp, a local MCP server (one Python file, standard library only) that gives AI agents read-only access to that data with your own NPReq API key;
  • the npreq plugin for Claude Code, which runs that server, asks for your key once and keeps it in your system's credential store, and adds a skill that tells Claude when to use each tool.

NPReq data is for information. It is not for clinical or licensing decisions: always confirm a requirement with the state board of nursing before you act on it.

You need an NPReq API key (https://npreq.com/) and Python 3.10 or newer as python3 on your PATH.

Install the plugin (Claude Code)

The plugin needs Claude Code v2.1.271 or later and works in Claude Code only. (Cowork skips a plugin server whose required, sensitive setting has no default, and an API key cannot have one.)

/plugin marketplace add Miles-Medical-Service/npreq-mcp
/plugin install npreq@npreq

On Claude Code 2.1.275 or later, one line does both: /plugin install npreq --marketplace Miles-Medical-Service/npreq-mcp.

On Windows, the plugin starts the server with python3. On many Windows machines python3 is only the Microsoft Store alias, which opens the Store instead of running Python. Before you enable the plugin, run python3 --version in a terminal: it must print Python 3.10 or newer. If it does not, install Python from python.org or the Microsoft Store, or turn off the python3.exe App Execution Alias (Settings > Apps > Advanced app settings) once a real python3 is on your PATH.

When the plugin is enabled, Claude Code asks for two settings:

Setting What it is
NPReq API key Your key (npq_live_..., or npq_test_... for staging). Masked when typed and stored in your system's credential store, not in a settings file.
NPReq API A choice of https://api.npreq.com (the default) or https://api-staging.npreq.com. There is no free-text address, because the key is sent there.

The plugin passes these two values to the server. It does not read an API key that is already set in your shell. The API choice also appears in /config; the key does not, because it is a sensitive setting.

The tools then appear as mcp__plugin_npreq_npreq__<tool>.

The tools

Every tool is exactly one read-only request to the NPReq REST API. No tool writes anything.

Tool Request it makes Scope your key needs Arguments
get_data_version GET /v1/meta none (public) none
list_states GET /v1/states states:read none
get_state GET /v1/states/{code} states:read code: two capital letters (TX, PR)
get_state_ce GET /v1/states/{code}/ce ce:read code: two capital letters
search_requirements GET /v1/search?q= search q: 2 to 64 letters, digits, spaces, hyphens, apostrophes or periods

A result is the API's JSON reply. An API error comes back as a tool error with the HTTP status, the API's error code and a fixed message; for 429 and 503 it says how many seconds to wait.

Everything the plugin runs, sends and fetches

  • Runs: python3 <plugin folder>/npreq_mcp.py, a local process that talks to Claude Code over stdin and stdout. It runs nothing else, installs nothing, and writes no files.

  • Sends, only to the API you chose (https://api.npreq.com or https://api-staging.npreq.com), over HTTPS:

    1. POST /v1/token with your API key in the Authorization header. This is the only request that carries the key. The reply is an access token that lasts 6 hours; the server keeps it in memory only and asks for a new one when fewer than 5 minutes are left, or once after a data request is refused with 401.
    2. The five GET requests in the table above, each with the access token (never the key) in the Authorization header, plus the state code or search text you or Claude passed as the tool's argument.

    Every request also carries Accept: application/json and User-Agent: npreq-mcp/<version>.

  • Fetches: only the API's JSON replies to those requests (at most 16 MB each). It never follows a redirect, since a redirect would carry the Authorization header to another address, and it checks the TLS certificate.

  • Nothing else: no telemetry, no analytics, no update checks, no other host.

Privacy

  • The NPReq API receives your key (at /v1/token only), the tool arguments (a state code or a search text), your IP address and the User-Agent above. It counts your requests against your plan's minute limit and monthly quota. What NPReq keeps and for how long is in the privacy policy: https://npreq.com/privacy.html. Use of the API is under the terms: https://npreq.com/terms.html.
  • Do not put personal or patient information in a search: the search text is sent to the API.
  • The server never writes your key or a token to its output, its log (one line per tool call, with the tool name and the status, on stderr), a tool result or an error. It takes the key out of its own environment once it has read it.
  • Results are curated requirement data with sources. The tools and the skill tell Claude to treat them as data, not instructions.

What happens when something is refused

  • A refused key is held. Once /v1/token answers 401 or 403, the server sends nothing more with the key. Every tool that needs a token answers at once with that status, and only get_data_version keeps working until you fix the key (or its IP allowlist) and restart. This is because every refusal counts toward the API's lockout of your IP address (10 in 10 minutes locks it for 15 minutes), so a retrying client can never lock you out.
  • A 429 or 5xx at /v1/token is temporary and is not held.
  • A revoked key, a lapsed subscription, or a scope your plan lacks stops the tools on the next call: the API checks the key behind every token on every request.

Without the plugin

Any MCP client that starts a local stdio server can run npreq_mcp.py directly. Set NPREQ_API_KEY in that client's server configuration (never on a command line or in a prompt), and optionally NPREQ_API_BASE, which accepts only an https:// origin and defaults to https://api.npreq.com. For example, in Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "npreq": {
      "command": "python3",
      "args": ["/path/to/npreq-mcp/npreq_mcp.py"],
      "env": { "NPREQ_API_KEY": "<your key>" }
    }
  }
}

On Windows, use python (or py -3) instead of python3, and a full path with forward slashes. Installed with pip install . from this folder, the server is also the npreq-mcp command.

The NPReq API documentation, with more client setups, is at https://account.npreq.com/account/docs.

Protocol

Newline-delimited JSON-RPC 2.0 on stdio. A request whose _meta carries io.modelcontextprotocol/protocolVersion 2026-07-28 is served statelessly by that revision. An initialize request selects the handshake of 2025-11-25, 2025-06-18 or 2025-03-26 for the life of the process. Any other version gets error -32022 with the supported list. The server offers tools only: no resources, prompts, sampling or elicitation.

Tests

python3 tests/test_npreq_mcp.py runs on Python 3.10 and 3.13 with no network: the API is a fake, and the child-process tests point the server at an address that refuses at once. They cover:

  • the five routes and their argument checks;
  • the error map;
  • token renewal and the single retry, and the refused key held for the session;
  • that redirects are never followed;
  • that the key never appears in output, logs, results or arguments;
  • the plugin's settings, and that the key the plugin passes wins over one set in the shell.

Security and licence

Report a vulnerability as described in SECURITY.md; please do not open a public issue for it. MIT licence: see LICENSE.

Metadata

Release files for npreq-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for npreq-mcp 0.1.0
File Size Uploaded Provenance Actions
npreq_mcp-0.1.0.tar.gz 24.6 kB With provenance Details for npreq_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for npreq-mcp 0.1.0
File Interpreter ABI Platform Actions
npreq_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for npreq_mcp-0.1.0-py3-none-any.whl

Total release size: 39.2 kB

Release files / npreq_mcp-0.1.0.tar.gz

Download URL npreq_mcp-0.1.0.tar.gz
Size 24.6 kB
Tags Source
SHA-256 checksum
How to use checksums
22403d862d13d2c31bb32ac5bf03fab5a3e3b8845e19a224c57aa24974d0b285
BLAKE2b-256 checksum
How to use checksums
3d3d7df93167faf48f9aa6c0a4bf8e01a847041237c203aae97ce40678b84c8a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / npreq_mcp-0.1.0-py3-none-any.whl

Download URL npreq_mcp-0.1.0-py3-none-any.whl
Size 14.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
04b373dbbe6bf09dab44d3059f45839df22d53f584075b8492d22868dd6a320f
BLAKE2b-256 checksum
How to use checksums
c28487453cdbfbc61a1f612f24fd326f1bd403d4602743d1841d88ec9ccf884c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for npreq-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for npreq_mcp-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page