Fergus MCP Server

A Model Context Protocol (MCP) server that integrates with the Fergus API, enabling AI assistants like Claude to interact with Fergus's job management platform.

Features

🔐 Secure authentication (PAT for local, OAuth 2.0 for remote)
🌐 Dual transport support: stdio (local CLI) and HTTP (remote web)
📋 26+ tools for jobs, customers, quotes, sites, time entries, and users
🛠️ Create, read, and update Fergus resources
🔄 Real-time data synchronization with Fergus API
💬 Built-in prompts for common workflows

Installation

This server supports two transport modes:

Stdio Transport: For local use with Claude Desktop (local mode)
HTTP Transport: For remote use with Claude Web or Claude Desktop (remote mode)

Option 1: Local Mode (Stdio) - Claude Desktop

The easiest way to use this MCP server locally with Claude Desktop:

claude mcp add fergus-mcp -- npx -y fergus-mcp --api-token YOUR_API_TOKEN

Or add it manually to your Claude Desktop config:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "fergus": {
      "command": "npx",
      "args": ["-y", "fergus-mcp", "--api-token", "YOUR_API_TOKEN"]
    }
  }
}

Option 2: Remote Mode (HTTP) - Remote Clients

Before you begin:

You can host your own version of this MCP server.
If you just want to try things quickly, we maintain a shared test instance at https://fergus-mcp-server.onrender.com/mcp, but we do not guarantee it will always be available.

Claude Web & Claude Desktop (Remote connectors)

Launch Claude Desktop (v1.8.2+) or visit claude.ai, open Settings → Model Context.
Enable Remote connectors, click Add remote server, and enter your hosted server’s domain (no path or protocol).
Approve the connector when prompted. Claude validates the domain, discovers the MCP metadata automatically, and opens the OAuth window supplied by your Fergus deployment.
Complete the Fergus OAuth sign-in. Claude stores the session and the connector appears in the Model Context panel. Repeat these steps for each team member that needs access.

ChatGPT Custom Connectors

In ChatGPT (web app), open Settings → Connectors → Remote MCP servers.
Select Add remote server, provide the public domain where your Fergus MCP server is hosted, and confirm.
ChatGPT fetches the server manifest; approve the prompt to trust the domain and follow the Fergus OAuth flow. When the redirect completes, the connector appears under My connectors for future chats.

Cursor IDE (v0.45+)

In Cursor, open Settings → MCP and toggle Enable remote MCPs.
Click Add remote MCP, supply the public domain for your Fergus MCP deployment, and confirm. Cursor validates the well-known endpoints and prompts you through the OAuth sign-in.
Once the handshake finishes, select the fergus connector inside your chat sidebar whenever you want Cursor to call Fergus tools.

Tip: If you rotate OAuth credentials or change PUBLIC_URL, re-run these client setup steps so each client refreshes its metadata and tokens.

Local Development

Clone this repository
Install dependencies:
```
pnpm install
```
Build the project:
```
pnpm run build
```

Run in development mode:

Stdio mode (for testing with local MCP clients):

pnpm run dev -- --api-token YOUR_API_TOKEN

HTTP mode (for testing remote server):

# Create .env file with OAuth credentials
cp .env.example .env
# Edit .env with your configuration
pnpm run dev:http

Configuration

Stdio Mode (Local)

Personal Access Token (PAT) is required. Get yours from your Fergus account settings.

Option 1: Command-line argument (Recommended)

npx fergus-mcp --api-token YOUR_API_TOKEN

Option 2: Environment variable

Create a .env file:

FERGUS_API_TOKEN=your_fergus_api_token_here

HTTP Mode (Remote)

OAuth 2.0 credentials are required. Configure in .env:

# Required OAuth Configuration
COGNITO_USER_POOL_ID=us-east-1-xxxxx
COGNITO_CLIENT_ID=your_client_id
COGNITO_CLIENT_SECRET=your_client_secret
COGNITO_REGION=us-east-1
COGNITO_DOMAIN=auth.fergus.com
OAUTH_REDIRECT_URI=https://your-domain.com/oauth/callback

# Server Configuration
HTTP_PORT=3100
PUBLIC_URL=https://your-domain.com

See .env.example for complete configuration options.

Optional Configuration

--base-url: Override the default Fergus API base URL
FERGUS_BASE_URL: Environment variable for base URL

Available Tools

This server provides 26+ tools organized by resource type:

Jobs (5 tools)

get-job: Get details for a specific job by ID
list-jobs: List all jobs with filtering and sorting
create-job: Create a new job (draft or finalized)
update-job: Update existing draft job
finalize-job: Convert draft job to active status

Quotes (7 tools)

get-quote: Get basic quote information
get-quote-detail: Get comprehensive quote with sections and line items
list-quotes: List quotes with filtering
create-quote: Create quote with sections and line items
update-quote: Update draft quote sections (by quote ID)
update-quote-version: Update draft quote sections (by version number)

Customers (3 tools)

get-customer: Get customer details
list-customers: List customers with search
create-customer: Add new customer
update-customer: Modify customer details

Sites (3 tools)

get-site: Get site details
list-sites: List sites with filtering
create-site: Add new site
update-site: Modify site details

Users (3 tools)

get-user: Get user/team member details
list-users: List users with filtering
update-user: Update user details

Time Entries (2 tools)

get-time-entry: Get time entry details
list-time-entries: List time entries with filtering

Built-in Prompts (3)

job-creation-assistant: Guided workflow for creating jobs
quote-generator: Help creating comprehensive quotes
weekly-report: Generate job status summaries

Usage Examples

Once connected, you can ask Claude:

"Show me all active jobs in Fergus"
"Create a quote for job #12345"
"List all customers in Auckland"
"Update the address for site #456"
"Show me this week's time entries"
"Create a new job for ABC Corp at their main office"

Development

Project Structure

fergus-mcp/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── config.ts             # Configuration management
│   ├── fergus-client.ts      # Fergus API client wrapper
│   ├── resources/            # MCP resource handlers
│   └── tools/                # MCP tool handlers
├── package.json
├── tsconfig.json
└── README.md

Building

pnpm run build

Running in Dev Mode

Stdio mode:

pnpm run dev -- --api-token YOUR_API_TOKEN

HTTP mode:

pnpm run dev:http

Scripts

pnpm run build - Build the project
pnpm run dev - Run stdio server in development mode
pnpm run dev:http - Run HTTP server in development mode
pnpm start - Run built stdio server
pnpm start:http - Run built HTTP server

Deployment

Quick Deploy to Render (Recommended)

This server is ready to deploy to Render with Redis session storage:

Fork or clone this repository to your GitHub account
Create a new Blueprint on Render and connect your repository
Configure OAuth credentials in Render Dashboard (see DEPLOYMENT.md)
Deploy! Render will automatically provision:
- Node.js web service
- Redis instance for sessions
- SSL certificate
- Internal networking

See DEPLOYMENT.md for complete step-by-step instructions.

Other Hosting Providers

The server can also be deployed to:

Cloudflare Workers: Use Durable Objects for session storage
Vercel: Configure Redis via Vercel KV
Railway: Similar to Render, uses render.yaml
AWS/GCP/Azure: Deploy as containerized app with managed Redis

See .env.example for required environment variables.

Security

Stdio Mode (Local)

Never commit your Personal Access Token to version control
Use environment variables or CLI arguments for configuration
Server runs locally and communicates directly with Fergus API

HTTP Mode (Remote)

OAuth 2.0 with PKCE for secure authentication
Tokens stored in-memory (optionally Redis for multi-instance deployments)
HTTPS required in production
CORS and DNS rebinding protection enabled
Session-based token management with automatic refresh
No data stored or transmitted to third parties

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For issues and questions:

GitHub Issues: Create an issue
Fergus API Documentation: https://api.fergus.com/docs

Fergus MCP Server

A Model Context Protocol (MCP) server that integrates with the Fergus API, enabling AI assistants like Claude to interact with Fergus's job management platform.

Features

🔐 Secure authentication (PAT for local, OAuth 2.0 for remote)
🌐 Dual transport support: stdio (local CLI) and HTTP (remote web)
📋 26+ tools for jobs, customers, quotes, sites, time entries, and users
🛠️ Create, read, and update Fergus resources
🔄 Real-time data synchronization with Fergus API
💬 Built-in prompts for common workflows

Installation

This server supports two transport modes:

Stdio Transport: For local use with Claude Desktop (local mode)
HTTP Transport: For remote use with Claude Web or Claude Desktop (remote mode)

Option 1: Local Mode (Stdio) - Claude Desktop

The easiest way to use this MCP server locally with Claude Desktop:

claude mcp add fergus-mcp -- npx -y fergus-mcp --api-token YOUR_API_TOKEN

Or add it manually to your Claude Desktop config:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "fergus": {
      "command": "npx",
      "args": ["-y", "fergus-mcp", "--api-token", "YOUR_API_TOKEN"]
    }
  }
}

Option 2: Remote Mode (HTTP) - Remote Clients

Before you begin:

You can host your own version of this MCP server.
If you just want to try things quickly, we maintain a shared test instance at https://fergus-mcp-server.onrender.com/mcp, but we do not guarantee it will always be available.

Claude Web & Claude Desktop (Remote connectors)

Launch Claude Desktop (v1.8.2+) or visit claude.ai, open Settings → Model Context.
Enable Remote connectors, click Add remote server, and enter your hosted server’s domain (no path or protocol).
Approve the connector when prompted. Claude validates the domain, discovers the MCP metadata automatically, and opens the OAuth window supplied by your Fergus deployment.
Complete the Fergus OAuth sign-in. Claude stores the session and the connector appears in the Model Context panel. Repeat these steps for each team member that needs access.

ChatGPT Custom Connectors

In ChatGPT (web app), open Settings → Connectors → Remote MCP servers.
Select Add remote server, provide the public domain where your Fergus MCP server is hosted, and confirm.
ChatGPT fetches the server manifest; approve the prompt to trust the domain and follow the Fergus OAuth flow. When the redirect completes, the connector appears under My connectors for future chats.

Cursor IDE (v0.45+)

In Cursor, open Settings → MCP and toggle Enable remote MCPs.
Click Add remote MCP, supply the public domain for your Fergus MCP deployment, and confirm. Cursor validates the well-known endpoints and prompts you through the OAuth sign-in.
Once the handshake finishes, select the fergus connector inside your chat sidebar whenever you want Cursor to call Fergus tools.

Tip: If you rotate OAuth credentials or change PUBLIC_URL, re-run these client setup steps so each client refreshes its metadata and tokens.

Local Development

Clone this repository
Install dependencies:
```
pnpm install
```
Build the project:
```
pnpm run build
```

Run in development mode:

Stdio mode (for testing with local MCP clients):

pnpm run dev -- --api-token YOUR_API_TOKEN

HTTP mode (for testing remote server):

# Create .env file with OAuth credentials
cp .env.example .env
# Edit .env with your configuration
pnpm run dev:http

Configuration

Stdio Mode (Local)

Personal Access Token (PAT) is required. Get yours from your Fergus account settings.

Option 1: Command-line argument (Recommended)

npx fergus-mcp --api-token YOUR_API_TOKEN

Option 2: Environment variable

Create a .env file:

FERGUS_API_TOKEN=your_fergus_api_token_here

HTTP Mode (Remote)

OAuth 2.0 credentials are required. Configure in .env:

# Required OAuth Configuration
COGNITO_USER_POOL_ID=us-east-1-xxxxx
COGNITO_CLIENT_ID=your_client_id
COGNITO_CLIENT_SECRET=your_client_secret
COGNITO_REGION=us-east-1
COGNITO_DOMAIN=auth.fergus.com
OAUTH_REDIRECT_URI=https://your-domain.com/oauth/callback

# Server Configuration
HTTP_PORT=3100
PUBLIC_URL=https://your-domain.com

See .env.example for complete configuration options.

Optional Configuration

--base-url: Override the default Fergus API base URL
FERGUS_BASE_URL: Environment variable for base URL

Available Tools

This server provides 26+ tools organized by resource type:

Jobs (5 tools)

get-job: Get details for a specific job by ID
list-jobs: List all jobs with filtering and sorting
create-job: Create a new job (draft or finalized)
update-job: Update existing draft job
finalize-job: Convert draft job to active status

Quotes (7 tools)

get-quote: Get basic quote information
get-quote-detail: Get comprehensive quote with sections and line items
list-quotes: List quotes with filtering
create-quote: Create quote with sections and line items
update-quote: Update draft quote sections (by quote ID)
update-quote-version: Update draft quote sections (by version number)

Customers (3 tools)

get-customer: Get customer details
list-customers: List customers with search
create-customer: Add new customer
update-customer: Modify customer details

Sites (3 tools)

get-site: Get site details
list-sites: List sites with filtering
create-site: Add new site
update-site: Modify site details

Users (3 tools)

get-user: Get user/team member details
list-users: List users with filtering
update-user: Update user details

Time Entries (2 tools)

get-time-entry: Get time entry details
list-time-entries: List time entries with filtering

Built-in Prompts (3)

job-creation-assistant: Guided workflow for creating jobs
quote-generator: Help creating comprehensive quotes
weekly-report: Generate job status summaries

Usage Examples

Once connected, you can ask Claude:

"Show me all active jobs in Fergus"
"Create a quote for job #12345"
"List all customers in Auckland"
"Update the address for site #456"
"Show me this week's time entries"
"Create a new job for ABC Corp at their main office"

Development

Project Structure

fergus-mcp/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── config.ts             # Configuration management
│   ├── fergus-client.ts      # Fergus API client wrapper
│   ├── resources/            # MCP resource handlers
│   └── tools/                # MCP tool handlers
├── package.json
├── tsconfig.json
└── README.md

Building

pnpm run build

Running in Dev Mode

Stdio mode:

pnpm run dev -- --api-token YOUR_API_TOKEN

HTTP mode:

pnpm run dev:http

Scripts

pnpm run build - Build the project
pnpm run dev - Run stdio server in development mode
pnpm run dev:http - Run HTTP server in development mode
pnpm start - Run built stdio server
pnpm start:http - Run built HTTP server

Deployment

Quick Deploy to Render (Recommended)

This server is ready to deploy to Render with Redis session storage:

Fork or clone this repository to your GitHub account
Create a new Blueprint on Render and connect your repository
Configure OAuth credentials in Render Dashboard (see DEPLOYMENT.md)
Deploy! Render will automatically provision:
- Node.js web service
- Redis instance for sessions
- SSL certificate
- Internal networking

See DEPLOYMENT.md for complete step-by-step instructions.

Other Hosting Providers

The server can also be deployed to:

Cloudflare Workers: Use Durable Objects for session storage
Vercel: Configure Redis via Vercel KV
Railway: Similar to Render, uses render.yaml
AWS/GCP/Azure: Deploy as containerized app with managed Redis

See .env.example for required environment variables.

Security

Stdio Mode (Local)

Never commit your Personal Access Token to version control
Use environment variables or CLI arguments for configuration
Server runs locally and communicates directly with Fergus API

HTTP Mode (Remote)

OAuth 2.0 with PKCE for secure authentication
Tokens stored in-memory (optionally Redis for multi-instance deployments)
HTTPS required in production
CORS and DNS rebinding protection enabled
Session-based token management with automatic refresh
No data stored or transmitted to third parties

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For issues and questions:

GitHub Issues: Create an issue
Fergus API Documentation: https://api.fergus.com/docs