The Civis MCP server allows your LLM of choice to communicate with both the Platform API and data in Platform. This MCP server can be used with most AI tools offering MCP support, including Civis Studio, VSCode, OpenCode, Claude Code, Claude Desktop, and others.

The Civis MCP server enables you to ask questions or give an AI agent instructions like:

• Why did my most recent workflow fail?
• Add all of the tables in the salesforce_ingest schema as sources in my dbt project.
• How many donors are in the salesforce_ingest.customers table?

MCP Server in Civis Studio

The Civis MCP Server is pre-installed for Civis Studios. To learn more, see our Civis Studio Copilot Chat + MCP documentation.

Local VSCode Installation

Below are instructions for setting up a local VSCode installation to interact with a Civis MCP server using our civisanalytics/mcp-server docker image.

Prerequisites

• Docker installed and running https://docs.docker.com/get-started/get-docker/
• VSCode installed with the Copilot Chat Extension
• A Civis API Key

Configuration

While there are many ways to add an MCP Server to VSCode, we'll cover here how to add it to a workspace using an mcp.json file. 

Ensure you have MCP enabled. Open settings, and search for MCP:

Open a workspace, and create a new file .vscode/mcp.json. Add the following configuration:

{
	"servers": {
		"civis": {
			"type": "stdio",
			"command": "docker",
			"args": [
				"run",
				"--rm",
				"-i",
				"-e",
				"CIVIS_API_KEY",
				"civisanalytics/mcp-server:1.0"
			],
			"env": {
				"CIVIS_API_KEY": "${input:CIVIS_API_KEY}"
			}
		}
	},
	"inputs": [
		{
			"type": "promptString",
			"id": "CIVIS_API_KEY",
			"description": "Civis API Key",
			"password": true
		}
	]
}

Open the command palette, and select “Add Server”:

Then select “Install from Docker Image” and enter civisanalytics/mcp-server as the image name:

“Allow” the installation and configure its install location as you desire, then enter your Platform API key to start the server:

After your original install, you will be able manage your server directly from the mcp.json file. 

Use

Start your Civis MCP server, if it’s not already running. You can start or restart your server from your mcp.json file:

Open Copilot chat:

Be sure that Agent mode is selected

Start your conversation!

Claude Desktop Installation

Below are instructions for setting up Claude Desktop to interact with a Civis MCP server using our civisanalytics/mcp-server docker image.

Prequestites

• Docker installed and running https://docs.docker.com/get-started/get-docker/
• Claude Desktop Installed (https://claude.ai/download/)
• A Civis API Key

Configuration

1. In Claude Desktop, click on your name in the bottom left corner and select Settings
2. In the settings menu, select Developer
3. Click Edit Config
4. This should open your Finder/File Explorer, navigated to your claude_desktop_config.json file
5. Paste the following code into your json file. You may have existing arguments in the “preferences” section of your json file. Below we have demonstrated where the preferences should be configured with respect to the mcpServers code.

{
 "mcpServers": {
   "civis": {
     "command": "docker",
     "args": [
       "run",
       "-i",
       "--rm",
       "-e",
       "CIVIS_API_KEY",
       "civisanalytics/mcp-server"
     ],
     "env": {
       "CIVIS_API_KEY": "YOUR API KEY HERE"
     }
   }
 },
 "preferences": {
 }
}

6. Make sure to replace “YOUR API KEY HERE” with your API Key, generated by following these instructions.
7. Save and close the file.
8. Make sure Docker is running.
9. Close and Restart Claude desktop.
10. When you navigate back to Settings > Developer, the civis MCP server should show as running.

Updating Your API Key

When your API key expires, you can prompt the server to ask you for a new one by clearing the existing input by hovering over it in the mcp.json file and selecting “Clear”:

After clearing the input, restart your Civis MCP server to input your new API key.

Schema-Restricted Mode

The --schema parameter limits the server to read-only data exploration within a specific schema, disabling workflow tools and access to other schemas.

When enabled:

• Only data tools are available: run_query, list_tables, get_table, pull_data_list, publish_html_report
• Queries are wrapped with BEGIN READ ONLY;
• Queries must reference the configured schema

To enable, add "--schema", "your_schema" to the args. You can optionally add "--description", "context about your data" to help the AI understand the data.

{
  "mcpServers": {
    "civis": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-e", "CIVIS_API_KEY",
        "civisanalytics/mcp-server",
        "--schema", "analytics_mart"
      ],
      "env": {
        "CIVIS_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code Installation (Local, VS Code)

Below are instructions for setting up Claude Code to interact with a Civis MCP server using a local Python installation. It assumes you will be using the Claude Code VS Code extension, but the instructions are similar with just the Claude Code CLI.

Prerequisites

• Python 3.10 or higher installed
• VS Code installed
• Claude Code extension installed in VS Code
• A Civis API Key
• Git installed

Configuration

1. Install the Claude Code extension from the VS Code marketplace if you have not already.
2. Clone the repo and install the MCP server in its own environment:

git clone https://github.com/civisanalytics/mcp-server-civis.git
cd mcp-server-civis
python3 -m venv ~/civis-mcp-venv
source ~/civis-mcp-venv/bin/activate
pip install .

3. Add the MCP server to the Claude Code configuration.

Note: the instructions below will make the Civis MCP server so that it’s available for all of your local work with Claude Code, but if you only want to set it up for the specific project, see Anthropic’s documentation here.

Adding with the Claude Code CLI (recommended)

If you have the Claude Code CLI installed, as discussed here, you can run the following command:

claude mcp add --env CIVIS_API_KEY=${CIVIS_API_KEY} --scope local 
civis -- $(which mcp-server-civis)

Adding without the Claude Code CLI

If you don’t have the Claude Code CLI installed, then you can set up the MCP server for the VS Code extension by directly editing ~/.claude.json. Create ~/.claude.json if it does not already exist:

touch ~/.claude.json

Then find out where the MCP server was installed:

which mcp-server-civis

Finally, open ~/.claude.json and add the following, replacing the command path with the output of the which command and adding your Civis API key:

{
  "mcpServers": {
    "civis": {
      "command": "/Users/yourusername/civis-mcp-venv/bin/mcp-server-civis",
      "env": {
        "CIVIS_API_KEY": "<your api key>"
      }
    }
  }
}

You can test the installation by opening VS Code and asking Claude Code "What is my Civis user ID?"