mcp-server-redcap
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-redcap Export records where age > 18"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 with optional filters by field, record ID, or event |
| Import records from a JSON payload |
| Delete records by ID |
| Export a saved REDCap report by its ID |
| Export the mapping from field names to export names (required for checkbox fields) |
| Get the next available record ID respecting the project's auto-numbering |
Metadata
Tool | Description |
| Retrieve project-level information and settings |
| Export the data dictionary, optionally filtered by field or form |
| Export the project audit log, with filters by type, user, record, or date range |
| Export the repeating instruments/events configuration |
| Update the repeating instruments/events configuration |
Instruments & project design
Tool | Description |
| List all instruments with internal names and display labels |
| List arm/event/instrument mappings (longitudinal projects) |
| Add a new field to an instrument (round-trip through data dictionary) |
| Remove a field from the data dictionary |
| Update specific properties of a field without touching the rest |
| Create a new instrument |
| Delete an instrument and all its fields |
| Rename an instrument's internal name |
| Reposition a field within the data dictionary |
| Copy all fields of an instrument into a new one with a field-name prefix |
| Add an instrument to a longitudinal event |
| Remove an instrument from a longitudinal event |
Analysis
Tool | Description |
| Compact overview of the whole project: instruments, field counts, event matrix |
| Find all fields that reference a given field in branching logic or calculations |
| Scan all branching logic for references to non-existent fields |
Files
Tool | Description |
| Download a file attachment from a record field (returned as base64) |
| Upload a file to a record field (accepts base64 content) |
| Delete a file attachment from a record field |
| Export a PDF of one or more instruments for a record (returned as base64) |
Arms & events (longitudinal)
Tool | Description |
| List arms |
| Create or update arms |
| Delete arms by number |
| List events, optionally filtered by arm |
| Create or update events |
| Delete events by unique name |
Surveys
Tool | Description |
| Get a participant-specific survey URL for a record |
| List survey participants and their response status |
Related MCP server: Redash MCP Server
Installation
pip install mcp-server-redcapOr with uv:
uvx mcp-server-redcapREDCap 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 |
| Yes | Full REDCap API endpoint URL (e.g. |
| Yes | Project-level API token from REDCap → API → Generate Token |
| No | Set to |
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_hereUsage 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-redcapOr 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 devRun the MCP inspector for interactive local testing:
uv run mcp dev src/mcp_server_redcap/server.pyRun the server directly (stdio transport, for use with MCP clients):
uv run mcp-server-redcapProject 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 listsSee DESIGN.md for the full API reference and design rationale.
License
MIT
Available Tools
38 toolsadd_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_linkA
Get a unique survey link for a participant to complete 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: record: Record ID of the participant. instrument: Internal name of the survey instrument. event: Event name (longitudinal projects only). repeat_instance: Repeat instance number (default 1).
Returns: The survey URL as a plain string.
Inputs: record (required), instrument (required), event, repeat_instance. 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
Scored across 38 tools
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.
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.
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.
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
Related MCP Connectors
Connect AI clients to biomedical data and tools.
Query, explore, and manage your databases through natural conversation.
Send files and manage client uploads from a compatible AI agent.
Research briefs and file-based research tasks via MCP. Compare sources, check citations, or analyze authorized data and retrieve reports or files. RigorMed OAuth and available credits are required for task execution.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.13102MIT
- AlicenseBqualityDmaintenanceEnables interaction with Redash instances through a standardized interface, allowing users to execute SQL queries, manage data sources, and retrieve query results using natural language.42,645 npm1MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to manage Redash queries, dashboards, visualizations, and data sources via natural language.1512 npmMIT
- FlicenseNot gradedqualityAmaintenanceEnables 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.-