Factors MCP lets you create, run, and update Factors account research agents from anywhere that speaks MCP.

factors-mcp Setup Guide

Installing Python 3.11 and configuring the Factors MCP server across Mac, Windows, and Linux

Prerequisites

Before starting, you will need:

A Factors Agents API key
Terminal / Command Prompt access
AI application - here we will go with Claude Desktop as an example for setting up MCP.

Step 1 — Install Claude Desktop

Claude Desktop is the client that runs the MCP server. Install it before configuring anything.

macOS

Go to https://claude.ai/download
Download the macOS version and open the .dmg file
Drag Claude to your Applications folder
Launch Claude and sign in with your Anthropic account

Windows

Go to https://claude.ai/download
Download the Windows installer (.exe) and run it
Follow the installation prompts
Launch Claude and sign in with your Anthropic account

Linux

Note: Claude Desktop does not have an official Linux build. On Linux, use Cursor as the MCP client instead — see the Cursor config in the MCP Configuration section.

Step 2 — Install Python 3.11 and factors-mcp

Open the terminal inside your mac or windows.

macOS

Step 1 — Install Homebrew (if not already installed)

Check if Homebrew is installed:

brew --version

If the command is not found, install Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Note: After Homebrew installs, close the terminal window completely and open a fresh one before continuing. Homebrew will not be recognized in the same session.

Step 2 — Install Python 3.11

brew install python@3.11

Note: Even if you have another Python version on your system, this installs 3.11 separately via Homebrew. Do not try to replace the system Python.

Step 3 — Install factors-mcp

Use the Homebrew Python 3.11 directly — do not use the system python3:

 /opt/homebrew/bin/python3.11 -m pip install factors-mcp

Step 4 — Confirm install

/opt/homebrew/bin/python3.11 -m factors_mcp --help

Step 5 — Find the full Python path (for MCP config)

 which python3.11
 
# Expected output:
# /opt/homebrew/bin/python3.11

Windows

Step 1 — Install Python 3.11

Go to https://www.python.org/downloads/release/python-3119/
Download the "Windows installer (64-bit)"
Run the installer — check "Add Python to PATH" before clicking Install

Verify in Command Prompt:

python --version
 
# Expected:
# Python 3.11.x

Step 2 — Install factors-mcp

python -m pip install factors-mcp

Step 3 — Find the full Python path (for MCP config)

 where python
 
# Example output:
# C:\Users\YourName\AppData\Local\Programs\Python\Python311\python.exe
Note: Copy this full path — you will need it for the MCP config command field.

Linux (Ubuntu / Debian)

Step 1 — Install Python 3.11

sudo apt update

sudo apt install python3.11 python3.11-venv python3.11-distutils -y

Step 2 — Install pip for Python 3.11

curl -sS https://bootstrap.pypa.io/get-pip.py | python3.11

Step 3 — Install factors-mcp

python3.11 -m pip install factors-mcp

Step 4 — Find the full Python path

 which python3.11
 
# Expected:
# /usr/bin/python3.11

MCP Server Configuration

Once Python 3.11 and factors-mcp are installed, add the following to your MCP config file.

FACTORS_API_KEY

This is your Factors Agents API key. You can find it inside any published agent — it is the same key across all agents. Do not use a regular Factors project API key.

Config file locations

Claude Desktop (Mac)

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop (Win)

%APPDATA%\Claude\claude_desktop_config.json

Config JSON — macOS

 {
  "mcpServers": {
    "factors-ai": {
      "command": "python3.11",
      "args": ["-m", "factors_mcp"],
      "env": {
        "FACTORS_API_KEY": "your_agents_api_key_here"
      }
    }
  }
}

Note: If the MCP server does not appear after restarting, python3.11 may not be on your PATH. In that case replace the command value with the full path: /opt/homebrew/bin/python3.11

Config JSON — Windows

 {
  "mcpServers": {
    "factors-ai": {
      "command": "python3.11",
      "args": ["-m", "factors_mcp"],
      "env": {
        "FACTORS_API_KEY": "your_agents_api_key_here"
      }
    }
  }
}

Note: Replace the path with the actual output from the 'where python' command in Step 3.

Config JSON — Linux

 {
  "mcpServers": {
    "factors-ai": {
      "command": "python3.11",
      "args": ["-m", "factors_mcp"],
      "env": {
        "FACTORS_API_KEY": "your_agents_api_key_here"
      }
    }
  }
}

After Saving the Config

Fully quit and relaunch Claude Desktop — a simple window close is not enough. On Mac, right-click the Claude icon in the Dock and select Quit.
Open a new chat in Claude Desktop.
Look for the hammer icon (tools) at the bottom of the chat input box — click it.
You should see factors-ai listed as a connected MCP server with a green indicator.
If it appears, the setup is complete and Factors tools are ready to use in Claude.

Note: If you do not see the hammer icon or factors-ai is not listed, see the Troubleshooting section below.

Quick verification test

 # macOS / Linux
FACTORS_API_KEY=your_agents_api_key python3.11 -m factors_mcp
 
# Windows
set FACTORS_API_KEY=your_agents_api_key
python3.11 -m factors_mcp

If the server starts without errors, the setup is complete.

Troubleshooting

python3 still shows old version

Do not fight the system Python. Use the full absolute path to Python 3.11 in all commands and in the MCP config.

pip3: command not found

Use python3.11 -m pip install factors-mcp instead of pip3.

externally-managed-environment error

Add --break-system-packages to the pip install command.

MCP server not appearing in client

Confirm the command path in the config exactly matches the output of which python3.11 (Mac/Linux) or where python (Windows).

factors_mcp module not found

The install may have used a different Python. Re-run the pip install using the same absolute path: /opt/homebrew/bin/python3.11 -m pip install factors-mcp