JobNimbus MCP Server

This project provides a Model Context Protocol (MCP) server for interacting with the JobNimbus API. It allows AI assistants to access and manipulate JobNimbus data through standardized tools.

Features

• Complete JobNimbus API Integration: Access to Contacts, Jobs, Tasks, Products, Workflows, and Invoices
• Secure Access: Requires JobNimbus API key for authentication
• Easy Setup: Simple configuration for use with Cursor editor, Claude, and other AI assistants
• Cross-Platform: Works with any MCP-compatible client

Quick Start

1. With NPX (easiest):

   export JOBNIMBUS_API_KEY=your_api_key_here
   npx jobnimbus-mcp-server

2. With Claude Desktop: Edit ~/Library/Application Support/Claude/claude_desktop_config.json to point to the server

3. With Cursor: Create .mcp.json in your project with the server configuration

4. Local Installation: Clone, build and run:

   git clone https://github.com/yourusername/jobnimbus-mcp-server.git
   cd jobnimbus-mcp-server
   npm install
   npm run build
   npm start

Installation Options

Option 1: Install via NPX (Easiest)

You can install and run the server directly with NPX:

# Set your JobNimbus API key as an environment variable
export JOBNIMBUS_API_KEY=your_api_key_here

# Run the server directly with NPX
npx jobnimbus-mcp-server

Option 2: Clone the Repository

1. Clone this repository:

   git clone https://github.com/yourusername/jobnimbus-mcp-server.git
   cd jobnimbus-mcp-server

2. Prerequisites: Node.js (v18 or later) and npm.

3. Install Dependencies:

   npm install

4. API Key: Create a .env file in the root of the project with your JobNimbus API key:

   JOBNIMBUS_API_KEY=your_api_key_here

   Replace your_api_key_here with your actual key. Do not commit the .env file to version control.

5. Build and Run:

   npm run build
   npm start

Running the Server

1. Build the TypeScript code:

   npm run build

2. Start the server:

   npm start

   The server will connect via stdio and listen for MCP requests.

3. Development Mode (watches for changes and rebuilds/restarts):

   npm run dev

Using with Cursor Editor

To use this MCP server with the Cursor editor:

1. Create a .mcp.json file in your Cursor project root directory:

   {
     "mcpServers": {
       "jobnimbus-local-server": {
         "command": "npx",
         "args": ["jobnimbus-mcp-server"],
         "env": {
           "JOBNIMBUS_API_KEY": "your_api_key_here"
         }
       }
     }
   }

   Or if using a local installation:

   {
     "mcpServers": {
       "jobnimbus-local-server": {
         "command": "npm",
         "args": ["start"],
         "cwd": "/absolute/path/to/jobnimbus-mcp-server",
         "env": {
           "JOBNIMBUS_API_KEY": "your_api_key_here"
         }
       }
     }
   }

2. Restart Cursor to load the MCP configuration.

Using with Claude

The server can be used with Anthropic's Claude AI assistant which supports the Model Context Protocol:

1. Install Claude desktop app if you haven't already

2. Build your JobNimbus MCP server:

   npm run build

3. Create or edit Claude's configuration file:

   • On Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • On Windows: %APPDATA%\Claude\claude_desktop_config.json

4. Add the following configuration (adjust paths to your installation):

   {
     "mcpServers": {
       "jobnimbus-local-server": {
         "command": "/path/to/your/node",
         "args": [
           "/absolute/path/to/jobnimbus-mcp-server/dist/server.js"
         ],
         "env": {
           "JOBNIMBUS_API_KEY": "your_api_key_here"
         }
       }
     }
   }

   For example, with Node.js installed via NVM on Mac:

   {
     "mcpServers": {
       "jobnimbus-local-server": {
         "command": "/Users/username/.nvm/versions/node/v16.20.0/bin/node",
         "args": [
           "/Users/username/projects/jobnimbus-mcp-server/dist/server.js"
         ],
         "env": {
           "JOBNIMBUS_API_KEY": "your_api_key_here"
         }
       }
     }
   }

5. Restart Claude desktop app

6. When you're in a conversation with Claude, you can now use JobNimbus tools with commands like:

   • "Please list all contacts in my JobNimbus account"
   • "Create a new job for customer John Smith"
   • "Show me all invoices that are past due"
   • "Update the status of job J-12345 to 'In Progress'"

Using with Other AI Assistants

For other AI assistants that support the Model Context Protocol, use a similar configuration as shown above for Cursor.

Implemented Tools

This server implements MCP tools corresponding to the JobNimbus API endpoints:

Contacts

• jobnimbus_list_contacts: Get a list of contacts with optional filtering
• jobnimbus_get_contact: Get a specific contact by ID
• jobnimbus_create_contact: Create a new contact
• jobnimbus_update_contact: Update an existing contact

Jobs

• jobnimbus_list_jobs: Get a list of jobs with optional filtering
• jobnimbus_get_job: Get a specific job by ID
• jobnimbus_create_job: Create a new job
• jobnimbus_update_job: Update an existing job

Tasks

• jobnimbus_list_tasks: Get a list of tasks with optional filtering
• jobnimbus_get_task: Get a specific task by ID
• jobnimbus_create_task: Create a new task
• jobnimbus_update_task: Update an existing task

Products

• jobnimbus_list_products: Get a list of products with optional filtering
• jobnimbus_get_product: Get a specific product by ID
• jobnimbus_create_product: Create a new product
• jobnimbus_update_product: Update an existing product

Workflows

• jobnimbus_get_all_workflows: Get all workflows and their statuses
• jobnimbus_create_workflow: Create a new workflow
• jobnimbus_create_workflow_status: Create a new workflow status

Invoices

• jobnimbus_list_invoices: Get a list of invoices with optional filtering
• jobnimbus_get_invoice: Get a specific invoice by ID
• jobnimbus_create_invoice: Create a new invoice
• jobnimbus_update_invoice: Update an existing invoice
• jobnimbus_send_invoice: Send an invoice via email
• jobnimbus_record_invoice_payment: Record a payment against an invoice

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.