# Contractor Foreman by Cotlet

Connect an AI coding agent to Contractor Foreman to access project records, estimates, daily logs, and invoices. The package also provides a REST API and Python interface.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 2
- Author: cotletdev
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cotletdev/contractor-foreman-api-mcp-server
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/contractor-foreman-by-cotlet

## What it does

Contractor Foreman by Cotlet exposes application data through MCP tools. An agent can retrieve project information, inspect schedules, access estimates and invoices, and work with payment records, work orders, and inspections. The project includes 89 tools. Developers can also use a REST API or call operations from Python, with ready-made scripts available in `examples/`.

The self-hosted server runs in Python and relies on an authenticated Google Chrome session. Running `contractor-foreman-mcp connect` retrieves browser cookies through the Chrome DevTools Protocol and stores the session in `~/.config/contractor-foreman-api-mcp/session.json`. It does not read the account password. Local setup requires Python 3.11 or later, Google Chrome 144 or later, and permission to access the relevant Contractor Foreman modules.

MCP clients can connect over HTTP or stdio, including Claude Code and Codex. The local edition is restricted to noncommercial use. If the web app invalidates the session, the server needs access to Chrome to refresh its authentication. Because requests use the same internal endpoints as the Contractor Foreman web application, changes to those endpoints can affect compatibility.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Remote server: `https://cotlet.dev/mcp/v1/contractor-foreman/connect`

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http contractor-foreman https://cotlet.dev/mcp/v1/contractor-foreman/connect
```

2. **Platform CLI**
```bash
claude mcp add contractor-foreman-by-cotlet -- uvx contractor-foreman-api-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from contractor-foreman-api-mcp <command>

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add contractor-foreman-by-cotlet --url https://cotlet.dev/mcp/v1/contractor-foreman/connect
```

2. **Platform CLI**
```bash
codex mcp add contractor-foreman-by-cotlet -- uvx contractor-foreman-api-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from contractor-foreman-api-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "contractor-foreman-by-cotlet": {
            "url": "https://cotlet.dev/mcp/v1/contractor-foreman/connect"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "contractor-foreman-by-cotlet": {
            "command": "uvx",
            "args": [
                "contractor-foreman-api-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from contractor-foreman-api-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "contractor-foreman-by-cotlet": {
            "type": "http",
            "url": "https://cotlet.dev/mcp/v1/contractor-foreman/connect"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "contractor-foreman-by-cotlet": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "contractor-foreman-api-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from contractor-foreman-api-mcp <command>

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http contractor-foreman-by-cotlet https://cotlet.dev/mcp/v1/contractor-foreman/connect
```

2. **Platform CLI**
```bash
gemini mcp add contractor-foreman-by-cotlet uvx contractor-foreman-api-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from contractor-foreman-api-mcp <command>

## When to use it
- Retrieve Contractor Foreman project records through an AI agent
- Inspect schedules and daily work logs
- Access estimates, invoices, and payment records
- Review work orders, inspections, and change orders
- Call Contractor Foreman operations from Python scripts through the REST API

## Example prompts
- Find Contractor Foreman projects whose names contain Oak St.
- Show the estimates and unpaid invoices for the selected Contractor Foreman project.
- Retrieve the latest daily work logs for this project and summarize their entries.

## Similar
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16730
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40459
- [OpenWork MCP Gateway](https://affpapa.org/en/nevibecode/mcp/openwork-mcp-gateway.md) — MCP server · ★ 24271
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18779
- [Nhost](https://affpapa.org/en/nevibecode/mcp/nhost.md) — MCP server · ★ 9369
- [basebalance.cloud — x402 RPC & MCP gateway](https://affpapa.org/en/nevibecode/mcp/basebalancecloud-x402-rpc-mcp-gateway.md) — MCP server · ★ 7548

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md