Skip to main content
Glama

CDISC Library MCP Server โ€” Query clinical data standards (SDTM, ADaM, CDASH, CT) directly from AI assistants.

Python FastMCP License: MIT Tests API

๐ŸŒ Translations: ไธญๆ–‡ README ยท ๆ—ฅๆœฌ่ชž README


What is This?

The CDISC MCP Server connects AI assistants (Claude, VS Code Copilot, Cursor, etc.) to the CDISC Library REST API, exposing 11 structured tools for querying clinical trial data standards. Ask your AI assistant questions like:

"What variables are in the SDTM AE domain?"/m "Show me the ADSL variables in ADaM IG 1.3" "List all available Controlled Terminology packages"

For full setup instructions, see the User Manual โ†’. See Examples โ†’ for real conversation samples.


Related MCP server: CDISC Library MCP Server

Quick Start

0 ยท One-Line AI Install

Have an AI assistant install everything for you:

curl -fsSL https://raw.githubusercontent.com/Teninq/cdisc-mcp/main/install.md

Paste the output into Claude, Copilot, or any AI chat โ€” it will read the guide and walk you through the full setup interactively.


1 ยท Get a CDISC Library API Key

Register at https://library.cdisc.org and obtain a personal API key.

2 ยท Install

# Runtime only
pip install -e .

# With dev dependencies
pip install -e ".[dev]"

# With web explorer
pip install -e ".[web]"

3 ยท Set API Key

# Linux / macOS
export CDISC_API_KEY=your_key_here

# Windows โ€” Command Prompt
set CDISC_API_KEY=your_key_here

# Windows โ€” PowerShell
$env:CDISC_API_KEY = "your_key_here"

4 ยท Run

# Start MCP server (for AI assistant integration)
cdisc-mcp

# OR: Start Web Explorer (quick interactive testing)
python web/app.py

Web Explorer โ€” Quick Interactive Testing

The fastest way to verify your setup and explore tools without any AI client.

# 1. Install web dependencies
pip install -e ".[web]"

# 2. Set your API key
export CDISC_API_KEY=your_key_here   # Linux/macOS
set CDISC_API_KEY=your_key_here      # Windows CMD
$env:CDISC_API_KEY = "your_key_here" # Windows PowerShell

# 3. Start the bridge server
python web/app.py

# 4. Open in browser
#    โ†’ http://localhost:8080

The explorer provides:

  • Sidebar navigation โ€” all 11 tools organized by standard (SDTM / ADaM / CDASH / Terminology)

  • Auto-generated forms โ€” dropdowns for versions and domains, text inputs for variables

  • Live JSON responses โ€” syntax-highlighted, copyable output with response time

  • Bridge status indicator โ€” confirms your API key and connectivity

Tip: Use version strings with dashes โ€” 3-4 not 3.4, 1-3 not 1.3. Example: SDTM-IG 3-4, ADaM-IG 1-3, CDASH-IG 2-0


Available Tools

#

Tool

Standard

Description

1

list_products

โ€”

List all available CDISC standards and published versions

2

get_sdtm_domains

SDTM

List all datasets in a SDTM-IG version

3

get_sdtm_domain_variables

SDTM

List all variables in an SDTM domain/dataset

4

get_sdtm_variable

SDTM

Get full definition of a specific SDTM variable

5

get_adam_datastructures

ADaM

List all data structures in an ADaM-IG version

6

get_adam_variable

ADaM

Get definition of a specific ADaM variable

7

get_cdash_domains

CDASH

List all domains in a CDASH-IG version

8

get_cdash_domain_fields

CDASH

Get all data collection fields for a CDASH domain

9

list_ct_packages

CT

List all available Controlled Terminology packages

10

get_codelist

CT

Get definition and metadata of a CT codelist

11

get_codelist_terms

CT

List all valid terms in a CT codelist

Version Reference

Standard

Available Versions (use dashes)

SDTM-IG

3-4 ยท 3-3 ยท 3-2 ยท 3-1-3

ADaM-IG

1-3 ยท 1-2 ยท 1-1 ยท 1-0

CDASH-IG

2-1 ยท 2-0 ยท 1-1-1


Connect to an AI Assistant

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cdisc": {
      "command": "cdisc-mcp",
      "env": {
        "CDISC_API_KEY": "your_key_here"
      }
    }
  }
}

VS Code / Cursor

Add to .vscode/mcp.json or equivalent MCP config:

{
  "servers": {
    "cdisc": {
      "command": "cdisc-mcp",
      "env": {
        "CDISC_API_KEY": "your_key_here"
      }
    }
  }
}

Claude Code (CLI)

Claude Code supports MCP servers at two scopes: user (global, all projects) and project (local, current project only).

Option A โ€” CLI command (recommended)

# Add globally (available in all projects)
claude mcp add cdisc-mcp -e CDISC_API_KEY=your_key_here -- python -m cdisc_mcp.server

# Add for the current project only
claude mcp add cdisc-mcp --scope project -e CDISC_API_KEY=your_key_here -- python -m cdisc_mcp.server

# Verify the server was registered
claude mcp list

Option B โ€” Edit ~/.claude.json directly

{
  "mcpServers": {
    "cdisc-mcp": {
      "command": "python",
      "args": ["-m", "cdisc_mcp.server"],
      "env": {
        "CDISC_API_KEY": "your_key_here"
      }
    }
  }
}

Tip: If CDISC_API_KEY is already in your system environment, omit the env block entirely โ€” Claude Code inherits it automatically.

Once registered, confirm with /mcp in any Claude Code session, then use the tools conversationally:

User: What SDTM domains are defined in version 3.4?
Claude: [calls get_sdtm_domains with version="3-4"] ...

Using in Your Own Python Tools

You can call CDISC MCP tools programmatically from any Python script using the official MCP client SDK.

Install the client

pip install mcp

Minimal example

import asyncio
import os
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

SERVER = StdioServerParameters(
    command="python",
    args=["-m", "cdisc_mcp.server"],
    env={"CDISC_API_KEY": os.environ["CDISC_API_KEY"]},
)

async def main():
    async with stdio_client(SERVER) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List all available tools
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            # Call a tool
            result = await session.call_tool(
                "get_sdtm_domains",
                arguments={"version": "3-4"},
            )
            print(result.content[0].text)

asyncio.run(main())

Reusable helper

import asyncio, os, json
from contextlib import asynccontextmanager
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

_SERVER = StdioServerParameters(
    command="python",
    args=["-m", "cdisc_mcp.server"],
    env={"CDISC_API_KEY": os.environ["CDISC_API_KEY"]},
)

@asynccontextmanager
async def cdisc_session():
    """Async context manager that yields an initialised MCP session."""
    async with stdio_client(_SERVER) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            yield session

async def call(tool: str, **kwargs) -> dict:
    async with cdisc_session() as s:
        result = await s.call_tool(tool, arguments=kwargs)
        return json.loads(result.content[0].text)

# --- Usage examples ---
async def demo():
    # Fetch SDTM domains
    domains = await call("get_sdtm_domains", version="3-4")

    # Fetch all variables in the AE domain
    variables = await call("get_sdtm_domain_variables", version="3-4", domain="AE")

    # Look up a single variable
    aeterm = await call("get_sdtm_variable", version="3-4", domain="AE", variable="AETERM")

    print(aeterm)

asyncio.run(demo())

Available tool signatures (quick reference)

# Products / versions
await session.call_tool("list_products", {})

# SDTM
await session.call_tool("get_sdtm_domains",          {"version": "3-4"})
await session.call_tool("get_sdtm_domain_variables", {"version": "3-4", "domain": "AE"})
await session.call_tool("get_sdtm_variable",         {"version": "3-4", "domain": "AE", "variable": "AETERM"})

# ADaM
await session.call_tool("get_adam_datastructures",   {"version": "1-3"})
await session.call_tool("get_adam_variable",         {"version": "1-3", "data_structure": "ADSL", "variable": "USUBJID"})

# CDASH
await session.call_tool("get_cdash_domains",         {"version": "2-0"})
await session.call_tool("get_cdash_domain_fields",   {"version": "2-0", "domain": "AE"})

# Controlled Terminology
await session.call_tool("list_ct_packages",          {})
await session.call_tool("get_codelist",              {"package_id": "sdtmct-2024-03-29", "codelist_id": "C66781"})
await session.call_tool("get_codelist_terms",        {"package_id": "sdtmct-2024-03-29", "codelist_id": "AGEU"})

Version format: Always use dashes, not dots โ€” "3-4" not "3.4".


Architecture

MCP Client (Claude / VS Code / Cursor)
        โ”‚
        โ”‚  MCP protocol (stdio)
        โ–ผ
   server.py  โ”€โ”€โ”€โ”€ FastMCP tool registration
        โ”‚
        โ–ผ
   tools/  โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ domain functions (sdtm, adam, cdash, terminology, search)
        โ”‚
        โ–ผ
   client.py  โ”€โ”€โ”€โ”€โ”€ CDISCClient (async HTTP ยท TTL cache ยท retry)
        โ”‚
        โ”‚  HTTPS
        โ–ผ
   library.cdisc.org/api  โ”€โ”€โ”€โ”€ CDISC Library REST API

Key design decisions:

  • CDISCClient is a singleton async HTTP client with 1-hour TTL in-memory cache

  • Only 429 and 5xx responses are retried; 4xx raise immediately

  • Tool functions are pure async โ€” independently testable without patching

  • format_response() strips HAL _links metadata, extracts structured data for LLM consumption


Development

Development workflow (devel-first, branch & merge SOP): See Contributing Guide.

Running Tests

# Full suite with coverage (โ‰ฅ80% required)
pytest

# Specific modules
pytest tests/test_tools.py tests/test_client.py -v

# Single test
pytest tests/test_tools.py::test_list_products -v

Code Quality

ruff check src/ tests/    # Linting
mypy src/                 # Type checking

GitHub Branch Protection (Required Checks)

Configure main branch protection to require:

  • CI Tests / tests

  • CI Lint / lint

  • CI Types / types

Project Structure

src/cdisc_mcp/
โ”œโ”€โ”€ server.py              # FastMCP server + tool registration
โ”œโ”€โ”€ client.py              # Async HTTP client (cache, retry)
โ”œโ”€โ”€ config.py              # Config dataclass + env loader
โ”œโ”€โ”€ errors.py              # AuthenticationError, ResourceNotFoundError, RateLimitError
โ”œโ”€โ”€ response_formatter.py  # HAL response normalization
โ””โ”€โ”€ tools/
    โ”œโ”€โ”€ search.py          # list_products (product catalog)
    โ”œโ”€โ”€ sdtm.py            # SDTM domain/variable tools
    โ”œโ”€โ”€ adam.py            # ADaM datastructure/variable tools
    โ”œโ”€โ”€ cdash.py           # CDASH domain/field tools
    โ”œโ”€โ”€ terminology.py     # CT package/codelist tools
    โ””โ”€โ”€ _validators.py     # Path traversal guards
web/
โ”œโ”€โ”€ app.py                 # FastAPI bridge server
โ””โ”€โ”€ index.html             # Single-file browser explorer
tests/
โ”œโ”€โ”€ test_config.py
โ”œโ”€โ”€ test_client.py
โ”œโ”€โ”€ test_response_formatter.py
โ”œโ”€โ”€ test_tools.py
โ”œโ”€โ”€ test_errors.py
โ””โ”€โ”€ test_server.py

License

MIT license.


Built for clinical data professionals working with CDISC standards.

User Manual ยท Examples ยท CDISC Library ยท API Docs

Available Tools

12 tools
get_adam_datastructuresB

List all ADaM data structures for a given version.

Args: version: ADaM version, e.g. "1.3", "2.1"

Inputs: version (required). Returns: object

get_adam_variableB

Get the definition of a specific ADaM variable.

Args: version: ADaM version, e.g. "1.3" data_structure: Data structure name, e.g. "ADSL", "ADAE" variable: Variable name, e.g. "USUBJID", "AVAL"

Inputs: version (required), data_structure (required), variable (required). Returns: object

get_cdash_domain_fieldsB

Get all data collection fields for a CDASH domain.

Args: version: CDASH version, e.g. "2.0" domain: Domain code, e.g. "DM", "AE", "VS"

Inputs: version (required), domain (required). Returns: object

get_cdash_domainsB

List all CDASH domains for a given version.

Args: version: CDASH version, e.g. "2.0", "1.1"

Inputs: version (required). Returns: object

get_codelistA

Get a specific Controlled Terminology codelist definition.

Args: package_id: CT package identifier, e.g. "sdtmct-2024-03-29" codelist_id: Codelist concept ID or submission value, e.g. "C66781", "AGEU"

Inputs: package_id (required), codelist_id (required). Returns: object

get_codelist_termsB

List all valid terms in a CT codelist (max 100 shown, check has_more).

Args: package_id: CT package identifier codelist_id: Codelist concept ID or submission value

Inputs: package_id (required), codelist_id (required). Returns: object

get_sdtm_domainsA

List all SDTM domains for a given version.

Args: version: SDTM-IG version, e.g. "3.4", "3.3". Use list_products() first.

Inputs: version (required). Returns: object

get_sdtm_domain_variablesB

Get all variables defined in an SDTM domain.

Args: version: SDTM-IG version, e.g. "3.4" domain: Two-letter domain code, e.g. "DM", "AE", "LB"

Inputs: version (required), domain (required). Returns: object

get_sdtm_variableB

Get the full definition of a specific SDTM variable.

Args: version: SDTM-IG version, e.g. "3.4" domain: Domain code, e.g. "AE" variable: Variable name, e.g. "AETERM", "AEDECOD"

Inputs: version (required), domain (required), variable (required). Returns: object

list_ct_packagesA

List all available CDISC Controlled Terminology packages with release dates.

Inputs: no named parameters. Returns: object

list_productsA

List all available CDISC standards and their published versions. Use this first to discover available versions before querying specific content.

Inputs: no named parameters. Returns: object

search_cdiscB

Search across all CDISC standards by keyword.

Args: query: Search keyword, e.g. "adverse event", "AEDECOD", "demographics"

Inputs: query (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.8/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting specific CDISC standards (ADaM, CDASH, SDTM, Controlled Terminology) with no overlap. The tools are organized by standard type and operation level (list domains vs. get specific variables), making them easily distinguishable.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with clear prefixes indicating the standard (get_adam_, get_cdash_, get_sdtm_, get_codelist_, list_, search_). The naming is highly predictable and follows the same snake_case convention throughout.

    Tool Count5/5

    12 tools is well-scoped for a CDISC standards lookup server, covering multiple standards (ADaM, CDASH, SDTM, CT) with appropriate granularity. Each tool serves a specific purpose without redundancy, and the count supports comprehensive querying without being overwhelming.

    Completeness4/5

    The toolset provides excellent coverage for querying CDISC standards metadata, with list operations for discovery and get operations for detailed information. Minor gaps exist (e.g., no update/create/delete tools, but that's appropriate for a read-only reference server), and the search tool helps bridge any remaining gaps.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers