Clinic Laboratory MCP Server

Local Model Context Protocol server for following laboratory results in a small medical clinic. It stores synthetic patient data in SQLite and exposes tools to search patients, review current results, compare measurements over time, record new results, and manage pending exams.

This is the independent public server developed for the first CC3067 Networks project milestone. The console host that consumes it is maintained in a separate private repository.

Features

• Local MCP communication through the stdio transport.

• Persistent SQLite storage with foreign keys, indexes, constraints, and transactions.

• Repeatable synthetic dataset for demonstrations.

• Date, ownership, numeric value, reference interval, and pending-exam validation.

• Audit entries for result and pending-exam creation.

• Automated domain tests.

Related MCP server: sharp-on-fhir-mcp

MCP specification

The server is started as a local process. It does not expose an HTTP port or REST endpoints. During MCP initialization it publishes six tools and one resource.

Tools

Dates use YYYY-MM-DD. collected_at accepts an ISO 8601 date or timestamp. Test codes are normalized to uppercase and medical record matching is case-insensitive.

Domain validation failures are returned by MCP as tool errors. Examples include an unknown patient, an invalid date range, a future collection date, an inverted reference interval, fewer than two observations for comparison, and a pending exam assigned to another patient.

Resource

Requirements

• Python 3.11 or newer

• uv

• Node.js only when using MCP Inspector

Installation

Clone the public repository and install its locked environment:

git clone https://github.com/MiltonPolanco/clinic-lab-mcp-server.git
cd clinic-lab-mcp-server
uv sync --locked

Create or restore the demonstration database:

uv run clinic-lab-seed --reset

The default database is data/clinic.db. It is generated locally and ignored by Git.

Configuration

Set CLINIC_DB_PATH before starting the server to use another SQLite file:

$env:CLINIC_DB_PATH = "C:\data\clinic-demo.db"
uv run clinic-lab-seed --reset
uv run clinic-lab-mcp

Without this variable, the server uses the database under the repository's data directory.

Running the server

Start it directly over standard input/output:

uv run clinic-lab-mcp

An MCP host normally starts this process. Example configuration:

{
  "mcpServers": {
    "clinic_labs": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\absolute\\path\\to\\clinic-lab-mcp-server",
        "run",
        "clinic-lab-mcp"
      ]
    }
  }
}

Do not write diagnostic messages to standard output because MCP protocol messages use that stream. Application diagnostics should use standard error.

Demonstration

After resetting the database, a representative sequence is:

1. Call search_patients with {"query": "Ana"}. The returned record is P-1001.

2. Call get_latest_lab_results with {"medical_record": "P-1001"}.

3. Call compare_lab_results with {"medical_record": "P-1001", "test_code": "GLU"}. The seeded glucose values decrease from 112 to 104 mg/dL.

4. Call list_pending_exams with {"medical_record": "P-1001"} and retain the returned exam ID.

5. Call record_lab_result with the patient, GLU result data, and that pending_exam_id.

6. Call list_pending_exams again and verify that the completed exam is no longer returned.

MCP Inspector

Initialize the database and open the official Inspector:

uv run clinic-lab-seed --reset
npx -y @modelcontextprotocol/inspector uv run clinic-lab-mcp

Tests

Run all automated tests:

uv run pytest

Run them with branch and line coverage:

uv run pytest --cov=clinic_labs_mcp --cov-report=term-missing

Data model

• patients identifies each fictional patient by medical record.

• lab_results stores dated numeric observations and reference intervals.

• pending_exams tracks pending, completed, or cancelled orders and can reference the result that completed an order.

• audit_log records creation operations and their associated entity.

SQLite connections enable foreign keys and use transactions so a result and its matching pending-exam update either complete together or are rolled back together.

Source structure

src/clinic_labs_mcp/
  database.py   SQLite schema and connection setup
  service.py    Validation and domain operations
  server.py     MCP tools, resource, and stdio entry point
  seed.py       Repeatable synthetic demonstration data
tests/

Protocol notes

The implementation uses the official Python MCP SDK. Initialization negotiates capabilities through JSON-RPC 2.0, tools/list publishes the tool catalog, and tools/call invokes individual operations. The SDK handles protocol serialization while the functions in server.py implement the clinic behavior.

License

This academic project is provided for demonstration and evaluation purposes.