MCP Server Setup and Management

REDCap MCP Server: Setup and Management

Article ID	RC-MCP-01 — REDCap MCP Server: Setup and Management
Domain	MCP
Applies To	REDCap administrators; users of AI tools with Claude (Cowork / Claude desktop)
Prerequisite	RC-API-01 — REDCap API; RC-AI-01 — REDCap AI Tools: Overview & Security
Version	1.1
Last Updated	2026
Author	See KB-SOURCE-ATTESTATION.md
Source	MCP server install.sh and redcap_mcp_server.py (internal)
Related Topics	RC-API-01 — REDCap API; RC-AI-01 — REDCap AI Tools: Overview & Security

1. Overview¶

The REDCap MCP server is a small Python program that acts as a bridge between Claude (and other AI tools that support the Model Context Protocol) and your REDCap instance. Once it is running and registered, Claude can call REDCap API methods — exporting records, querying project metadata, checking connections, and more — directly from a conversation, without anyone copying and pasting data or writing custom scripts for each task.

MCP (Model Context Protocol) is an open standard that defines how AI assistants discover and call external tools. Registering the REDCap MCP server with the Claude desktop application tells Claude that a set of REDCap tools are available and how to invoke them. From that point forward, Claude can use those tools automatically whenever a conversation calls for them.

A single server instance handles one REDCap environment (production, test, or development). You can register multiple server instances — one per environment — so that Claude can query any of them in the same conversation while keeping environments clearly separated.

2. How It Works¶

The MCP server is a Python script (redcap_mcp_server.py) that wraps the REDCap API. When Claude needs to perform a REDCap action, the Claude desktop application starts the Python script as a subprocess, passes the request to it via standard input/output, and the script sends the corresponding HTTP POST to your REDCap API endpoint and returns the response.

Each registered server is given a unique name (e.g., redcap-prod, redcap-test) and is configured with the API URL for its environment. API tokens can be embedded in the server configuration as a default, or supplied per-call at runtime.

The server configuration lives in a single JSON file on your computer. The location depends on your operating system:

OS	Config file path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`

This file is read by the Claude desktop application at startup. Any change to it takes effect after you fully quit and relaunch Claude.

3. Prerequisites¶

Before running the setup script, confirm the following:

On the REDCap side: - The REDCap API is enabled system-wide (Control Center → Modules/Services Configuration — see RC-CC-06 — Control Center: Modules & Services Configuration). - You have an API token for at least one project in the target environment. See RC-API-01 — REDCap API Section 3 for how to request a token. - Your REDCap instance URL ends in /api/ (e.g., https://redcap.yourinstitution.edu/api/).

On your computer: - Python 3.10 or later is installed. To check: on macOS open Terminal and run python3 --version; on Windows open Command Prompt or PowerShell and run python --version. If Python is missing or older than 3.10, install it — on macOS via Homebrew (brew install python@3.11), on Windows from python.org (check "Add Python to PATH" during installation). - You have internet access to install Python packages via pip. - The Claude desktop application is installed.

4. Initial Setup¶

4.1 Obtain the server files¶

The MCP server consists of two files:

redcap_mcp_server.py — the server itself (do not edit this file)
install.sh — a one-time setup script (macOS only; Windows users follow Section 4.5 instead)

Save both files to a permanent location on your computer. The Python script must stay at that path after setup because the configuration will reference it by its full path. A dedicated folder works well — for example ~/redcap-mcp/ on macOS or C:\redcap-mcp\ on Windows.

4.2 Edit the install script (macOS)¶

Open install.sh in any text editor. Near the top, find the three URL variables and fill in the API endpoints for your environments:

REDCAP_URL_PROD="https://redcap.yourinstitution.edu/api/"
REDCAP_URL_TEST="https://redcap-test.yourinstitution.edu/api/"
REDCAP_URL_DEV="https://redcap-dev.yourinstitution.edu/api/"

If you only have one or two environments, that is fine — the script will still register all three entries in the config file, but you can remove unused servers afterward (see Section 6.3).

Note: The URL must end with a trailing slash and must use HTTPS. Plain HTTP is not supported and would expose your API tokens in transit.

4.3 Run the install script (macOS)¶

Open Terminal, navigate to the folder containing the files, and run:

bash install.sh

The script will: 1. Locate a compatible Python 3.10+ interpreter on your system. 2. Install two Python packages: mcp[cli] and requests. 3. Read or create ~/Library/Application Support/Claude/claude_desktop_config.json. 4. Add three server entries (redcap-prod, redcap-test, redcap-dev) to the config.

A successful run ends with output similar to:

✓ Done! Three MCP servers registered: redcap-prod, redcap-test, redcap-dev

4.4 Relaunch Claude¶

The Claude desktop application reads the config file only at startup. After setup completes:

macOS: Use Cmd+Q or right-click the Dock icon → Quit, then relaunch.
Windows: Right-click the Claude icon in the system tray → Quit, or close all windows and end the process in Task Manager, then relaunch.

Simply closing the chat window is not sufficient — Claude must be fully quit and relaunched for the new server entries to take effect.

The MCP servers will now be available. You can verify the connection by asking Claude: "Check my REDCap connection on redcap-prod, token [your token]" — or by setting a default token first (see Section 5) and then asking without providing the token inline.

4.5 Windows Setup (manual)¶

The install.sh script is a bash script and does not run natively on Windows. Windows users configure the server manually in three steps.

Step 1 — Install Python dependencies.

Open Command Prompt or PowerShell and run:

pip install "mcp[cli]" requests

Step 2 — Create or edit the Claude config file.

The config file lives at:

%APPDATA%\Claude\claude_desktop_config.json

You can open this path directly by pressing Win+R, typing %APPDATA%\Claude, and pressing Enter. If the Claude folder or claude_desktop_config.json file does not exist yet, create them.

Open the file in a text editor (Notepad works, but a JSON-aware editor such as VS Code is easier) and add your server entries. Use full Windows paths and double backslashes in all path strings:

{
  "mcpServers": {
    "redcap-prod": {
      "command": "python",
      "args": ["C:\\redcap-mcp\\redcap_mcp_server.py"],
      "env": {
        "REDCAP_URL": "https://redcap.yourinstitution.edu/api/"
      }
    },
    "redcap-test": {
      "command": "python",
      "args": ["C:\\redcap-mcp\\redcap_mcp_server.py"],
      "env": {
        "REDCAP_URL": "https://redcap-test.yourinstitution.edu/api/"
      }
    }
  }
}

Adjust the path in args to wherever you saved redcap_mcp_server.py. Remove any environment entries you do not need.

Note: JSON requires backslashes to be doubled (\\) inside strings. A single backslash will cause a parse error and the server will not load.

Step 3 — Relaunch Claude as described in Section 4.4.

5. Token Configuration¶

5.1 Supplying a token per call¶

By default, no token is stored in the server configuration. You can supply a token at any time by including it in your message to Claude:

"Export the instruments from redcap-test, token ABC123XYZ"

Claude will pass that token directly to the MCP server for that call. The token is not stored anywhere between conversations.

5.2 Setting a default token in the config¶

If you work frequently with a single project, you can embed a default token in the server configuration so you do not have to include it in every request.

Open claude_desktop_config.json in a text editor (see Section 2 for the path on your OS). Locate the server entry you want to update and add a REDCAP_TOKEN key to its env block.

macOS example:

"redcap-prod": {
  "command": "/usr/local/bin/python3",
  "args": ["/Users/yourname/redcap-mcp/redcap_mcp_server.py"],
  "env": {
    "REDCAP_URL": "https://redcap.yourinstitution.edu/api/",
    "REDCAP_TOKEN": "your32charactertokenhere"
  }
}

Windows example:

"redcap-prod": {
  "command": "python",
  "args": ["C:\\redcap-mcp\\redcap_mcp_server.py"],
  "env": {
    "REDCAP_URL": "https://redcap.yourinstitution.edu/api/",
    "REDCAP_TOKEN": "your32charactertokenhere"
  }
}

After saving the file, fully quit and relaunch Claude. Claude will now use that token as the default for any call made to that server, unless a token is explicitly provided in the conversation.

Security note: Tokens stored in the config file are readable by any process running as your user account. Do not store tokens for sensitive production data on shared or multiuser machines. For high-sensitivity projects, always supply the token per call rather than embedding it.

6. Managing Servers After Initial Setup¶

All server management is done by editing claude_desktop_config.json directly. The install script (macOS) only needs to be run once; after that, all changes on both platforms are made by hand. See Section 2 for the config file path on your OS.

The file has this structure:

{
  "mcpServers": {
    "redcap-prod": { ... },
    "redcap-test": { ... },
    "redcap-dev":  { ... }
  }
}

Each key under mcpServers is the server name Claude will use to identify it. The value is an object with three fields:

Field	Purpose
`command`	Full path to the Python executable
`args`	List containing the full path to `redcap_mcp_server.py`
`env`	Environment variables — at minimum `REDCAP_URL`; optionally `REDCAP_TOKEN`

After any edit to this file, fully quit and relaunch Claude before testing.

6.1 Updating a server's API URL¶

If your REDCap instance moves to a new URL, open the config file and change the REDCAP_URL value in the relevant server's env block:

"redcap-prod": {
  "command": "/usr/local/bin/python3",
  "args": ["/Users/yourname/redcap-mcp/redcap_mcp_server.py"],
  "env": {
    "REDCAP_URL": "https://new-url.yourinstitution.edu/api/"
  }
}

Save the file, quit Claude, and relaunch.

6.2 Adding a new server¶

To add a fourth environment — for example, a dedicated training instance — add a new entry under mcpServers. Choose a unique key name (it becomes the server name Claude will reference):

{
  "mcpServers": {
    "redcap-prod": { ... },
    "redcap-test": { ... },
    "redcap-dev":  { ... },
    "redcap-training": {
      "command": "/usr/local/bin/python3",
      "args": ["/Users/yourname/redcap-mcp/redcap_mcp_server.py"],
      "env": {
        "REDCAP_URL": "https://redcap-training.yourinstitution.edu/api/"
      }
    }
  }
}

All four server entries share the same redcap_mcp_server.py file — you do not need a separate copy per environment. The REDCAP_URL environment variable is what tells each instance which endpoint to contact.

Tip: Server names like redcap-prod or redcap-training are what you use when talking to Claude: "Check the connection on redcap-training, token XYZ". Choose names that are short and easy to type conversationally.

6.3 Removing a server¶

To remove a server, delete its entire entry from the mcpServers object. For example, to remove redcap-dev:

Before:

{
  "mcpServers": {
    "redcap-prod": { ... },
    "redcap-test": { ... },
    "redcap-dev":  { ... }
  }
}

After:

{
  "mcpServers": {
    "redcap-prod": { ... },
    "redcap-test": { ... }
  }
}

Save, quit Claude, and relaunch. The removed server will no longer appear and Claude will not attempt to use it.

Note: Removing a server from the config does not delete redcap_mcp_server.py or affect your REDCap instance in any way. It only removes Claude's registration of that connection.

6.4 Renaming a server¶

To rename a server, change its key in mcpServers. For example, to rename redcap-dev to redcap-sandbox:

"redcap-sandbox": {
  "command": "/usr/local/bin/python3",
  "args": ["/Users/yourname/redcap-mcp/redcap_mcp_server.py"],
  "env": {
    "REDCAP_URL": "https://redcap-dev.yourinstitution.edu/api/"
  }
}

After relaunching Claude, use the new name in conversation. Saved prompts or habits that reference the old name will need to be updated.

7. Verifying the Connection¶

After setup or after making changes, confirm that a server is reachable by asking Claude to run a connection check:

"Check my connection on redcap-prod, token [your token]"

A successful response looks like:

{ "status": "success", "data": "16.1.3" }

The data field returns the REDCap version number. If the check fails, the response will include an error message — see Section 8 for troubleshooting.

You can also verify which servers are registered by opening claude_desktop_config.json directly and reviewing the mcpServers object. There is no in-app list view of registered servers in the current Claude desktop release.

8. Troubleshooting¶

Claude does not recognize the server name / says it has no REDCap tools. The most common cause is that Claude was not fully restarted after the config was changed. On macOS, closing the window is not the same as quitting — use Cmd+Q or right-click the Dock icon and select Quit. On Windows, right-click the system tray icon and choose Quit, or end the Claude process in Task Manager. Then relaunch.

ERROR: Python 3.10 or later is required during install (macOS). Python is either not installed or the version is too old. Install a compatible version (brew install python@3.11) and re-run install.sh.

python is not recognized as a command (Windows). Python was installed without adding it to PATH. Reinstall Python from python.org and check "Add Python to PATH" during setup. Alternatively, use the full path to the Python executable in the config (e.g., C:\\Users\\yourname\\AppData\\Local\\Programs\\Python\\Python311\\python.exe). Run where python in Command Prompt to find the correct path.

No module named 'mcp' error when Claude tries to call the server. The Python packages were not installed, or a different Python interpreter is being used than the one that installed them. Re-run pip install "mcp[cli]" requests (Windows) or re-run install.sh (macOS). Confirm that the command value in the config file points to the same Python executable — run which python3 (macOS) or where python (Windows) to find it.

Config file fails to load / Claude starts but servers are missing (Windows). The most common cause is malformed JSON — single backslashes in paths are a frequent mistake. Every backslash in a Windows path must be doubled: C:\\redcap-mcp\\redcap_mcp_server.py, not C:\redcap-mcp\redcap_mcp_server.py. Paste the file contents into a JSON validator to catch errors before relaunching Claude.

No REDCap URL provided error. The REDCAP_URL environment variable is missing from the server's env block in the config file. Open the config, confirm the key is spelled correctly, and ensure the URL ends with /api/. Save, quit, and relaunch.

No API token provided error. The token was not included in the message to Claude and no REDCAP_TOKEN default is set in the config. Either include the token in your message or add it to the env block as described in Section 5.2.

HTTP 401 Unauthorized. The token is invalid, belongs to a different project, or has been revoked. Retrieve a fresh token from the project's API page in REDCap.

HTTP 403 Forbidden. The token is valid but the user does not have the API Export or API Import right in that project. A project administrator must grant the appropriate right via the User Rights page.

Connection check succeeds but record exports return no data. Confirm the token belongs to a project that has records. Also check whether the user account is assigned to a Data Access Group — DAG-scoped tokens only see records within their DAG (see RC-DAG-01 — Data Access Groups).

9. Security Considerations¶

The REDCap MCP server runs locally on your machine. API calls go directly from your computer to your REDCap instance over HTTPS — they do not pass through any external service or Anthropic's servers. The server script enforces SSL certificate validation on every request; this cannot be disabled.

Tokens embedded in the config file are stored in plaintext on your local filesystem. On a personal computer this is generally acceptable, but you should be aware of the following:

Do not commit claude_desktop_config.json to a version-controlled repository.
Do not store tokens for production projects with sensitive research data on shared or multiuser machines. Use per-call token supply instead.
If you suspect a token has been compromised, revoke it from the REDCap Control Center (Users → API Tokens) immediately and request a new one.

See also: RC-API-01 — REDCap API Section 3.3 — Token Security for general API token guidance.

RC-API-01 — REDCap API (API fundamentals, token management, available methods)
RC-AI-01 — REDCap AI Tools: Overview & Security (overview of AI capabilities in REDCap)
RC-CC-06 — Control Center: Modules & Services Configuration (system-level API enable/disable)
RC-USER-03 — User Rights: Configuring User Privileges (where API Export/Import rights are granted)
RC-DAG-01 — Data Access Groups (how DAG membership affects API token scope)