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.2
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
Synonyms	how do i set up the redcap mcp server; connect claude to redcap; register the mcp server with claude desktop; model context protocol for redcap api; let claude export records and query metadata; configure multiple mcp servers for prod test and dev; where is the mcp json config file; install the redcap mcp python script

---

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 (standard installer)	%APPDATA%\Claude\claude_desktop_config.json
Windows (Microsoft Store / MSIX build)	%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\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.

Critical for Windows Store installs: If you installed Claude from the Microsoft Store (the MSIX/packaged build), the app does not read %APPDATA%\Claude\. The package sandbox redirects it to a LocalCache path under %LOCALAPPDATA%\Packages\Claude_<id>\... (the <id> is a random-looking string unique to your machine, e.g. Claude_pzs8sxrjxfjjc). Writing to %APPDATA%\Claude\ will appear to succeed but the app will never see it, and Settings → Developer will keep showing "no servers configured." Do not guess the path — let the app tell you. Open Settings → Developer and click Edit Config; it opens the exact file the app reads. Edit or paste into whatever opens, and you are guaranteed to be editing the right file regardless of install type.

---

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. Before starting, read Section 4.6 — the Windows-specific pitfalls below cause the large majority of failed setups, and knowing them up front saves considerable time.

Step 1 — Install Python.

First confirm Python 3.10+ is actually installed. In PowerShell, run python --version. If you see a real version number (e.g. Python 3.14.6), skip to Step 2.

If instead you get "Python was not found; run without arguments to install from the Microsoft Store," that is not a real Python — it is a Windows App Execution Alias placeholder. Install Python from python.org using the standard "Windows installer (64-bit)," and on the first installer screen check "Add python.exe to PATH." A per-user install (do not check "use admin privileges") is sufficient and avoids needing local administrator rights. After installing, open a new PowerShell window (PATH changes do not reach already-open windows) and confirm python --version. If the Store placeholder still intercepts, turn off the python.exe / python3.exe toggles under Settings → Apps → Advanced app settings → App execution aliases.

Step 2 — Install Python dependencies.

In PowerShell or Command Prompt:

python -m pip install "mcp[cli]" requests

Step 3 — Find the Python path for the config.

The config needs the full path to python.exe. Note that where python does nothing in PowerShell — where is an alias for a different cmdlet there. Use one of these instead:

where.exe python

(Get-Command python).Source

Use the path under ...\Programs\Python\... — ignore any path under ...\WindowsApps\..., which is the Store placeholder, not a working interpreter.

Step 4 — Open the correct config file.

Do not navigate to %APPDATA%\Claude by hand — on the Microsoft Store build that is the wrong location (see Section 2). Instead, open Claude and go to Settings → Developer → Edit Config. This opens the exact claude_desktop_config.json the app reads, wherever it actually lives. If the file has existing content, do not overwrite the whole file — add your server entries inside the existing mcpServers object and leave everything else intact.

Add your server entries using 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 5 — Relaunch Claude as described in Section 4.4. On Windows, "fully quit" means the system tray, not the window — right-click the Claude icon in the system tray (it may be hidden under the ^ overflow arrow) and choose Quit, or end all Claude processes in Task Manager. Closing the window leaves the app running and it will not re-read the config.

4.6 Windows pitfalls and a safe scripted write

Four Windows-specific traps account for most failed setups. All are avoidable:

1. Wrong config location (Store build). Covered in Section 2 — the Microsoft Store build ignores %APPDATA%\Claude\. Always reach the file via Settings → Developer → Edit Config rather than typing a path.
2. The BOM problem. If you write the config from PowerShell, do not use Set-Content -Encoding utf8 in Windows PowerShell 5.1 — it prepends a byte-order mark (BOM) that makes the app's JSON parser reject the file, and the servers silently fail to load. Either paste into the editor that Edit Config opens, or write the file with a BOM-free method (below).
3. where python returns nothing. Use where.exe python or (Get-Command python).Source (Section 4.5, Step 3).
4. The "Python was not found" placeholder. It is a Store alias, not Python (Section 4.5, Step 1).

If you prefer to write the file from PowerShell rather than pasting into the editor, this writes UTF-8 without a BOM and targets whatever path Edit Config revealed:

$config = @'
{
  "mcpServers": {
    "redcap-prod": {
      "command": "C:\\Users\\you\\AppData\\Local\\Programs\\Python\\Python314\\python.exe",
      "args": ["C:\\path\\to\\redcap_mcp_server.py"],
      "env": { "REDCAP_URL": "https://redcap.yourinstitution.edu/api/" }
    }
  }
}
'@
[System.IO.File]::WriteAllText("<PATH FROM EDIT CONFIG>", $config)

Note: The Python version number is baked into the command path (e.g. Python314). If you later upgrade Python, that folder name changes and every server entry breaks — update the command path in each entry after any Python upgrade.

---

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.

Windows Store build: Settings → Developer shows "no servers configured" even though you edited the config. You edited %APPDATA%\Claude\claude_desktop_config.json, but the Microsoft Store (MSIX) build reads from a sandboxed LocalCache path instead (see Section 2). The app never saw your file. Fix: open Settings → Developer → Edit Config, which opens the file the app actually reads, and put your mcpServers entries there. To confirm the true path, the button reveals something like ...\AppData\Local\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json.

Windows: config looks correct but servers still don't load (BOM). If you wrote the file with PowerShell's Set-Content -Encoding utf8 (Windows PowerShell 5.1), it added a byte-order mark that the JSON parser rejects. Rewrite the file BOM-free with [System.IO.File]::WriteAllText(path, text) (see Section 4.6), or simply paste the content into the editor that Edit Config opens.

Windows: you accidentally overwrote the whole config file. Writing the file instead of editing it replaces any existing content. The claude_desktop_config.json only holds MCP server entries — your projects, connected folders, login, and history live in separate files (config.json, Local Storage, IndexedDB) in the same folder and are not affected. Restore the lost server entries by re-adding them; nothing else needs recovery. To avoid this, always add to the existing mcpServers object rather than replacing the file.

Windows: where python prints nothing. where is a PowerShell alias, not the path-finder. Use where.exe python or (Get-Command python).Source.

Windows: python reports "Python was not found … Microsoft Store." That message is a Windows App Execution Alias placeholder, not an installed Python. Install from python.org with "Add python.exe to PATH" checked, open a new terminal, and retry (see Section 4.5, Step 1).

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.

---

10. Related Articles

• 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)