Skip to main content
Glama
mcp-server-redcap

mcp-server-redcap

by msicilia

mcp-server-redcap

A Model Context Protocol (MCP) server for interacting with REDCap (Research Electronic Data Capture) instances.

Exposes 38 tools covering data access, project design, file management, and longitudinal project structure. Designed for use with LLM agents that need to query or build REDCap projects in natural language conversations.

Tools

Records

Tool

Description

export_records

Export records with optional filters by field, record ID, or event

import_records

Import records from a JSON payload

delete_records

Delete records by ID

export_report

Export a saved REDCap report by its ID

export_field_names

Export the mapping from field names to export names (required for checkbox fields)

generate_next_record_name

Get the next available record ID respecting the project's auto-numbering

Metadata

Tool

Description

get_project_info

Retrieve project-level information and settings

get_metadata

Export the data dictionary, optionally filtered by field or form

export_logging

Export the project audit log, with filters by type, user, record, or date range

export_repeating_instruments_events

Export the repeating instruments/events configuration

import_repeating_instruments_events

Update the repeating instruments/events configuration

Instruments & project design

Tool

Description

get_instruments

List all instruments with internal names and display labels

get_instrument_event_mappings

List arm/event/instrument mappings (longitudinal projects)

add_field

Add a new field to an instrument (round-trip through data dictionary)

remove_field

Remove a field from the data dictionary

update_field

Update specific properties of a field without touching the rest

add_instrument

Create a new instrument

delete_instrument

Delete an instrument and all its fields

rename_instrument

Rename an instrument's internal name

move_field

Reposition a field within the data dictionary

clone_instrument

Copy all fields of an instrument into a new one with a field-name prefix

assign_instrument_to_event

Add an instrument to a longitudinal event

unassign_instrument_from_event

Remove an instrument from a longitudinal event

Analysis

Tool

Description

get_project_structure

Compact overview of the whole project: instruments, field counts, event matrix

check_field_references

Find all fields that reference a given field in branching logic or calculations

validate_branching_logic

Scan all branching logic for references to non-existent fields

Files

Tool

Description

export_file

Download a file attachment from a record field (returned as base64)

import_file

Upload a file to a record field (accepts base64 content)

delete_file

Delete a file attachment from a record field

export_pdf

Export a PDF of one or more instruments for a record (returned as base64)

Arms & events (longitudinal)

Tool

Description

export_arms

List arms

import_arms

Create or update arms

delete_arms

Delete arms by number

export_events

List events, optionally filtered by arm

import_events

Create or update events

delete_events

Delete events by unique name

Surveys

Tool

Description

export_survey_link

Get a participant-specific survey URL for a record

export_survey_participant_list

List survey participants and their response status

Related MCP server: Redash MCP Server

Installation

pip install mcp-server-redcap

Or with uv:

uvx mcp-server-redcap

REDCap version compatibility

The server works against any REDCap instance running version 8.0 or later. Most tools are available from version 6.x, but export_pdf requires 8.x. Repeating instruments (export_repeating_instruments_events, import_repeating_instruments_events) require 6.16+. Tools that are unavailable on a given instance return a plain error string rather than crashing.

The current REDCap version of the connected instance is included in the output of get_project_structure.

Configuration

The server reads connection details from environment variables:

Variable

Required

Description

REDCAP_URL

Yes

Full REDCap API endpoint URL (e.g. https://redcap.example.org/api/)

REDCAP_TOKEN

Yes

Project-level API token from REDCap → API → Generate Token

REDCAP_VERIFY_SSL

No

Set to false to skip SSL verification (default: true)

Create a .env file in your working directory and the server will load it automatically:

REDCAP_URL=https://redcap.example.org/api/
REDCAP_TOKEN=your_project_token_here

Usage with Claude Code

Add the server to your Claude Code MCP configuration:

claude mcp add redcap -e REDCAP_URL=https://redcap.example.org/api/ \
                      -e REDCAP_TOKEN=your_token -- uvx mcp-server-redcap

Or edit .claude/settings.json manually:

{
  "mcpServers": {
    "redcap": {
      "command": "uvx",
      "args": ["mcp-server-redcap"],
      "env": {
        "REDCAP_URL": "https://redcap.example.org/api/",
        "REDCAP_TOKEN": "your_project_token_here"
      }
    }
  }
}

Development

git clone https://github.com/msicilia/mcp-server-redcap
cd mcp-server-redcap
uv sync --extra dev

Run the MCP inspector for interactive local testing:

uv run mcp dev src/mcp_server_redcap/server.py

Run the server directly (stdio transport, for use with MCP clients):

uv run mcp-server-redcap

Project structure

src/mcp_server_redcap/
├── __init__.py
├── __main__.py          # python -m mcp_server_redcap
├── server.py            # FastMCP server factory and entry point
├── connection.py        # REDCap project connection (lazy, singleton)
└── tools/
    ├── __init__.py
    ├── records.py       # record CRUD, field names, next record name
    ├── metadata.py      # project info, data dictionary, logging, repeating instruments
    ├── instruments.py   # instrument listing, field and instrument mutations
    ├── analysis.py      # project structure overview, reference and logic validation
    ├── files.py         # file attachments and PDF export
    ├── arms_events.py   # longitudinal arms and events CRUD
    └── surveys.py       # survey links and participant lists

See DESIGN.md for the full API reference and design rationale.

License

MIT

Available Tools

38 tools
add_fieldA

Add a new field to an existing instrument.

Exports the current data dictionary, inserts the new field, and imports the updated dictionary back. The operation is atomic from REDCap's perspective.

Args: form_name: Internal name of the instrument to add the field to. field_name: Variable name for the new field (lowercase, underscores, no spaces). field_type: One of: text, notes, calc, radio, checkbox, yesno, truefalse, select, slider, file, descriptive. field_label: Display label shown to data-entry users. choices: Choice definitions for radio/checkbox/select fields, formatted as "1, Label 1 | 2, Label 2". Ignored for other types. required: Whether the field must be filled before saving the record. branching_logic: Show/hide logic expression (e.g. "[age] > 18"). field_note: Helper text displayed below the field. section_header: Section header to display above this field. validation: Validation type for text fields (e.g. integer, number, date_ymd, email, phone). validation_min: Minimum allowed value (for validated text fields). validation_max: Maximum allowed value (for validated text fields). field_annotation: REDCap action tags and annotations (e.g. @HIDDEN). after_field: Insert the new field immediately after this field name. If None, the field is appended at the end of the instrument.

Returns: Confirmation message with the count of updated fields.

Inputs: form_name (required), field_name (required), field_type (required), field_label (required), +10 more. Returns: result

add_instrumentA

Add a new instrument (form) to the project.

Creates the instrument by inserting a placeholder descriptive field. REDCap requires at least one field per instrument; the placeholder can be removed later once real fields have been added via add_field.

Note: the instrument display label defaults to the prettified form_name and can only be changed in the REDCap UI (Designer → instrument name).

Args: form_name: Internal name for the instrument (lowercase, underscores, no spaces).

Returns: Confirmation message with the placeholder field name.

Inputs: form_name (required). Returns: result

assign_instrument_to_eventA

Assign an instrument to an event in a longitudinal project.

Args: instrument: Internal form name of the instrument. event: Unique event name (e.g. 'baseline_arm_1'). arm_num: Arm number the event belongs to (default 1).

Returns: Confirmation message, or an error if the project is not longitudinal.

Inputs: event (required), instrument (required), arm_num. Returns: result

check_field_referencesA

Find every field that references a given field in branching logic or calculations.

Run this before removing or renaming a field to avoid breaking the project. Returns all fields whose branching_logic or calculated formula reference field_name.

Args: field_name: Variable name to search for.

Returns: JSON object with a list of referencing fields, or a confirmation that no references exist.

Inputs: field_name (required). Returns: result

clone_instrumentA

Clone all fields of an instrument into a new instrument.

Each cloned field name is prefixed with field_prefix to avoid collisions. Branching logic is cleared on cloned fields because it references the original field names; update it manually with update_field after cloning.

Args: source_form: Internal name of the instrument to clone. new_form_name: Internal name for the new instrument. field_prefix: Prefix to prepend to every cloned field name (e.g. 'v2_' turns 'age' into 'v2_age').

Returns: Confirmation message with the count of cloned fields.

Inputs: source_form (required), field_prefix (required), new_form_name (required). Returns: result

delete_armsA

Delete arms from a longitudinal REDCap project.

Args: arms: List of arm numbers to delete.

Returns: Confirmation message with the count of deleted arms.

Inputs: arms (required). Returns: result

delete_eventsB

Delete events from a longitudinal REDCap project.

Args: events: List of unique event names to delete.

Returns: Confirmation message with the count of deleted events.

Inputs: events (required). Returns: result

delete_fileA

Delete a file attachment from a REDCap record field.

Args: record: Record ID containing the file. field: Name of the file upload field. event: Event name (longitudinal projects only).

Returns: Confirmation message.

Inputs: field (required), record (required), event. Returns: result

delete_instrumentA

Delete an instrument and all its fields from the project.

Removes every field that belongs to the instrument. REDCap will reject the operation if the instrument contains the record-ID field.

Args: form_name: Internal name of the instrument to delete.

Returns: Confirmation message with the count of removed fields.

Inputs: form_name (required). Returns: result

delete_recordsA

Delete records from the REDCap project by record ID.

Args: record_ids: List of record IDs to delete.

Returns: Confirmation message with the count of deleted records.

Inputs: record_ids (required). Returns: result

export_armsA

Export arms for a longitudinal REDCap project.

Args: arms: Specific arm numbers to export. None exports all arms.

Returns: JSON array of arms with arm_num and name fields.

Inputs: arms. Returns: result

export_eventsA

Export events for a longitudinal REDCap project.

Args: arms: Filter to specific arm numbers. None exports events for all arms.

Returns: JSON array of events with event_name, arm_num, day_offset, and other fields.

Inputs: arms. Returns: result

export_field_namesA

Export the list of export field names for the project.

Checkbox fields have different export names (e.g. 'chk___1', 'chk___2') than their original field name. Use this to resolve the correct names before exporting or referencing checkbox data.

Args: field: Filter to a specific field name. None returns all fields.

Returns: JSON array of objects with original_field_name and export_field_name.

Inputs: field. Returns: result

export_fileA

Export a file attachment from a REDCap record field.

Args: record: Record ID containing the file. field: Name of the file upload field. event: Event name (longitudinal projects only). repeat_instance: Repeat instance number for repeating instruments/events.

Returns: JSON object with base64-encoded file content, filename, and content type.

Inputs: field (required), record (required), event, repeat_instance. Returns: result

export_loggingA

Export the audit log for the REDCap project.

Args: log_type: Filter by event type. One of: 'export', 'manage', 'user', 'record', 'record_add', 'record_edit', 'record_delete', 'lock_record', 'page_view'. None returns all types. user: Filter to a specific REDCap username. record: Filter to a specific record ID. begin_time: Start of date range as ISO 8601 string (e.g. '2024-01-01T00:00:00'). end_time: End of date range as ISO 8601 string.

Returns: JSON array of log entries.

Inputs: user, record, end_time, log_type, +1 more. Returns: result

export_pdfA

Export a PDF of one or all instruments for a record.

Args: record: Record ID to export. None exports all records (use with caution). event: Event name (longitudinal projects only). instrument: Specific instrument to export. None exports all instruments. repeat_instance: Repeat instance number for repeating instruments/events. compact_display: If True, uses compact PDF layout.

Returns: JSON object with base64-encoded PDF content.

Inputs: event, record, instrument, compact_display, +1 more. Returns: result

export_recordsA

Export records from the REDCap project.

Args: fields: Specific field names to export. None exports all fields. records: Specific record IDs to export. None exports all records. events: Specific event names to export (longitudinal projects only). raw_or_label: 'raw' for coded values, 'label' for choice labels. export_checkbox_label: Export checkbox field labels instead of 0/1. limit: Maximum number of records to return (default 1000).

Returns: JSON array of records.

Inputs: limit, events, fields, records, +2 more. Returns: result

export_repeating_instruments_eventsA

Export the repeating instruments and events configuration.

Requires REDCap 6.16 or later. Returns an error message on older instances.

Returns: JSON array of repeating instrument/event definitions, or an empty array if the project has no repeating instruments or events.

Inputs: no named parameters. Returns: result

export_reportA

Export a saved REDCap report by its ID.

Args: report_id: The numeric ID of the report (visible in the REDCap URL when viewing the report).

Returns: JSON array of report rows.

Inputs: report_id (required). Returns: result

export_survey_participant_listA

Export the list of survey participants for an instrument.

The instrument must be enabled as a survey in REDCap. Returns an error if surveys are not enabled or the instrument is not a survey.

Args: instrument: Internal name of the survey instrument. event: Event name (longitudinal projects only).

Returns: JSON array of participant records with email, name, and response status.

Inputs: instrument (required), event. Returns: result

generate_next_record_nameA

Generate the next available record name for the project.

Use this before importing a new record to obtain a valid, unused record ID that respects the project's auto-numbering scheme.

Returns: The next record name as a string.

Inputs: no named parameters. Returns: result

get_instrument_event_mappingsA

Get the mapping of instruments to events (longitudinal projects only).

Returns: JSON array of arm/event/instrument mappings, or an error message if the project is not longitudinal.

Inputs: no named parameters. Returns: result

get_instrumentsA

Get the list of instruments (forms/surveys) in the REDCap project.

Returns: JSON array of instruments with their internal names and display labels.

Inputs: no named parameters. Returns: result

get_metadataA

Get the data dictionary (metadata) for the REDCap project.

Returns field definitions including type, label, choices, validation, branching logic, and required status.

Args: fields: Filter to specific field names. None returns all fields. forms: Filter to specific instrument/form names. None returns all forms.

Returns: JSON array of field definitions.

Inputs: forms, fields. Returns: result

get_project_infoA

Get information about the REDCap project.

Returns project title, PI name, creation time, record count, and other project-level settings.

Returns: JSON object with project metadata.

Inputs: no named parameters. Returns: result

get_project_structureA

Return a compact structural overview of the REDCap project.

Useful as a first call when starting work on an existing project. Returns instruments with field counts and type breakdowns. For longitudinal projects, includes the full event/instrument matrix.

Returns: JSON object describing the project structure.

Inputs: no named parameters. Returns: result

import_armsA

Import (create or update) arms in a longitudinal REDCap project.

Args: data: JSON array of arm objects, each with arm_num and name fields. override: If True, existing arms not in the import will be deleted.

Returns: Confirmation message with the count of imported arms.

Inputs: data (required), override. Returns: result

import_eventsB

Import (create or update) events in a longitudinal REDCap project.

Args: data: JSON array of event objects with event_name, arm_num, day_offset, etc. override: If True, existing events not in the import will be deleted.

Returns: Confirmation message with the count of imported events.

Inputs: data (required), override. Returns: result

import_fileA

Import (upload) a file into a REDCap record field.

Args: record: Record ID to attach the file to. field: Name of the file upload field. file_name: Name to give the file in REDCap. content_base64: Base64-encoded file content. event: Event name (longitudinal projects only). repeat_instance: Repeat instance number for repeating instruments/events.

Returns: Confirmation message.

Inputs: field (required), record (required), file_name (required), content_base64 (required), +2 more. Returns: result

import_recordsA

Import records into the REDCap project.

Args: data: JSON array string of records to import. Each record must include the project's record ID field.

Returns: Confirmation message with the count of imported records.

Inputs: data (required). Returns: result

import_repeating_instruments_eventsA

Import (create or update) repeating instruments and events configuration.

Requires REDCap 6.16 or later. Returns an error message on older instances.

Args: data: JSON array of repeating instrument/event objects. Each object should have event_name, form_name, and custom_form_label fields.

Returns: Confirmation message with the count of imported definitions.

Inputs: data (required). Returns: result

move_fieldA

Move a field to a new position in the data dictionary.

Field order controls the layout of data-entry screens and surveys.

Args: field_name: Variable name of the field to move. after_field: Move the field immediately after this field name. If None, the field is moved to the end of its own instrument.

Returns: Confirmation message.

Inputs: field_name (required), after_field. Returns: result

remove_fieldA

Remove a field from the project data dictionary.

Exports the current data dictionary, removes the field, and imports the updated dictionary back.

Note: REDCap will reject the removal of the record-ID field and may reject removals that would break branching logic or calculated fields in other instruments.

Args: field_name: Variable name of the field to remove.

Returns: Confirmation message, or an error if the field was not found.

Inputs: field_name (required). Returns: result

rename_instrumentA

Rename an instrument by updating the form_name on all its fields.

Note: this changes the internal name only. The display label shown in the REDCap UI must be updated separately in Designer.

Args: old_form_name: Current internal name of the instrument. new_form_name: New internal name (lowercase, underscores, no spaces).

Returns: Confirmation message with the count of updated fields.

Inputs: new_form_name (required), old_form_name (required). Returns: result

unassign_instrument_from_eventA

Remove an instrument from an event in a longitudinal project.

Args: instrument: Internal form name of the instrument. event: Unique event name (e.g. 'baseline_arm_1').

Returns: Confirmation message, or an error if the mapping did not exist.

Inputs: event (required), instrument (required). Returns: result

update_fieldA

Update properties of an existing field in the data dictionary.

Only the properties you pass will be changed; all other properties are preserved exactly as they are. Exports the full dictionary, patches the target field, and imports it back.

Args: field_name: Variable name of the field to update. field_label: New display label. field_note: New helper text shown below the field. required: Set to True to make the field required, False to make it optional. branching_logic: New show/hide logic expression. choices: New choice definitions for radio/checkbox/select fields, formatted as "1, Label 1 | 2, Label 2". validation: New validation type for text fields. validation_min: New minimum allowed value. validation_max: New maximum allowed value. field_annotation: New action tags and annotations. section_header: New section header above this field.

Returns: Confirmation message, or an error if the field was not found.

Inputs: field_name (required), choices, required, field_note, +7 more. Returns: result

validate_branching_logicA

Scan all branching logic expressions for references to non-existent fields.

Checks every field's branching_logic for [field_name] tokens that do not match any field in the data dictionary. For longitudinal projects, event names in [event_name][field_name] syntax are excluded from the check.

Returns: A confirmation message if all references are valid, or a JSON object listing every broken reference with its location.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 38 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, with the export_* family differentiated by target (records, report, files, PDF, arms, events, surveys). A few pairs like get_project_info vs get_project_structure could initially confuse agents, but their descriptions separate metadata from structural overview.

    Naming Consistency5/5

    All 38 tools follow a consistent verb_noun pattern using lowercase with underscores (e.g., delete_file, get_metadata, import_records). There are no mixed naming conventions or vague verbs, making the API highly predictable.

    Tool Count4/5

    38 tools is a substantial surface, but it maps to the full breadth of REDCap functionality (records, files, metadata, instruments, arms, events, surveys, project structure). Each tool has a specific job, and the count feels justified for a comprehensive integration, though it borders on heavy.

    Completeness4/5

    The tool set covers the core REDCap workflows: record CRUD, file attachments, data dictionary editing, instrument/event management, longitudinal arms/events, and survey links. Obvious gaps include user/role management and project-level settings updates, but these are peripheral to most programmatic REDCap interactions.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables LLM-based agents to interact with FHIR healthcare data through natural language prompts, providing full CRUD operations on FHIR resources, document processing, and semantic search capabilities.
      13
      102
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables interaction with Redash instances through a standardized interface, allowing users to execute SQL queries, manage data sources, and retrieve query results using natural language.
      4
      2,645 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables LLM-based agents and MCP-compatible clients to query and manipulate clinical data on a FHIR-compliant backend through natural-language prompts, including CRUD operations, document ingestion, semantic search, and LOINC terminology lookup.
      -