# NetBox MCP Server

---

## Table of Contents

- [Running in Cursor](#️-running-in-cursor)
- [Getting Started](#-getting-started)
  - [Prerequisites](#️-prerequisites)
  - [Installation & Setup](#-installation--setup)
  - [Set tool environment variables](#-set-tool-environment-variables)
- [Connect the MCP Server to Claude (or other MCP clients)](#-connect-the-mcp-server-to-claude-or-other-mcp-clients)
- [Docker Deployment (Production or Development)](#-docker-deployment-production-or-development)
- [Server-Sent Events (SSE)](#-server-sent-events-sse)
- [Additional CLI commands](#-additional-cli-commands)
- [Adding New Tools](#-adding-new-tools)
- [Questions & Support](#-questions--support)
- [NetBox MCP Server Setup](#-netbox-mcp-server-setup)
  - [Environment Variables](#1-environment-variables)
  - [Tool Registration](#2-tool-registration)
  - [Usage in Cursor](#3-usage-in-cursor)
  - [Testing](#4-testing)
  - [Adding More Tools](#5-adding-more-tools)

---

## ��️ Running in Cursor

You can run this MCP server directly inside the Cursor IDE. Here's how:

1. **Open the Project**
   - Launch Cursor and open this project folder.

2. **Install Dependencies**
   - Open the built-in terminal in Cursor (View → Terminal or `Ctrl+``).
   - Run:
     ```sh
     npm install
     ```

3. **Set Environment Variables**
   - Create a `.env` file in the project root if it doesn't exist.
   - Add your API keys as described in the [Set tool environment variables](#-set-tool-environment-variables) section below.

4. **Run the MCP Server**
   - In the Cursor terminal, start the server:
     ```sh
     node mcpServer.js
     ```
   - For Server-Sent Events (SSE) support, use:
     ```sh
     node mcpServer.js --sse
     ```

5. **Test the Server**
   - You can use the Cursor terminal to run test commands, or connect to the server from compatible MCP clients (such as Claude Desktop) as described below.

6. **View Output**
   - All logs and output will appear in the Cursor terminal pane.

> **Tip:** You can edit code, manage files, and run all commands without leaving Cursor.

---

## 🚦 Getting Started

### ⚙️ Prerequisites

Before starting, please ensure you have:

- [Node.js (v18+ required, v20+ recommended)](https://nodejs.org/)
- [npm](https://www.npmjs.com/) (included with Node)

Warning: if you run with a lower version of Node, `fetch` won't be present. Tools use `fetch` to make HTTP calls. To work around this, you can modify the tools to use `node-fetch` instead. Make sure that `node-fetch` is installed as a dependency and then import it as `fetch` into each tool file.

### 📥 Installation & Setup

**1. Install dependencies**

Run from your project's root directory:

```sh
npm install
```

### 🔐 Set tool environment variables

In the `.env` file, you'll see environment variable placeholders, one for each workspace that the selected tools are from. For example, if you selected requests from 2 workspaces, e.g. Acme and Widgets, you'll see two placeholders:

```
ACME_API_KEY=
WIDGETS_API_KEY=
```

Update the values with actual API keys for each API. These environment variables are used inside of the generated tools to set the API key for each request. You can inspect a file in the `tools` directory to see how it works.

```javascript
// environment variables are used inside of each tool file
const apiKey = process.env.ACME_API_KEY;
```

**Caveat:** This may not be correct for every API. The generation logic is relatively simple - for each workspace, we create an environment variable with the same name as the workspace slug, and then use that environment variable in each tool file that belongs to that workspace. If this isn't the right behavior for your chosen API, no problem! You can manually update anything in the `.env` file or tool files to accurately reflect the API's method of authentication.

## 👩‍💻 Connect the MCP Server to Claude (or other MCP clients)

You can connect your MCP server to any MCP client. Here we provide instructions for connecting it to Claude Desktop.

**Step 1**: Note the full path to node and the `mcpServer.js` from the previous step.

**Step 2**. Open Claude Desktop → **Settings** → **Developers** → **Edit Config** and add a new MCP server:

```json
{
  "mcpServers": {
    "<server_name>": {
      "command": "<absolute/path/to/node>",
      "args": ["<absolute/path/to/mcpServer.js>"]
    }
  }
}
```

Restart Claude Desktop to activate this change. Make sure the new MCP is turned on and has a green circle next to it. If so, you're ready to begin a chat session that can use the tools you've connected.

**Warning**: If you don't supply an absolute path to a `node` version that is v18+, Claude (and other MCP clients) may fall back to another `node` version on the system of a previous version. In this case, the `fetch` API won't be present and tool calls will not work. If that happens, you can a) install a newer version of node and point to it in the command, or b) import `node-fetch` into each tool as `fetch`, making sure to also add the `node-fetch` dependency to your package.json.

### Additional Options

#### 🐳 Docker Deployment (Production or Development)

For Docker-based deployments, you can use the provided Dockerfile:

**1. Build Docker image**

```sh
docker build -t netbox-mcp-server .
```

**2. Run the Docker container**

```sh
docker run -it --rm --env-file=.env -p 3000:3000 netbox-mcp-server
```

- The server will start inside the container. Adjust the port mapping as needed.
- You can connect to this server from Cursor or any compatible MCP client as described above.

**3. (Optional) Integrate with Claude Desktop**

Add Docker server configuration to Claude Desktop (Settings → Developers → Edit Config):

```json
{
  "mcpServers": {
    "netbox-mcp-server": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file=.env", "-p", "3000:3000", "netbox-mcp-server"]
    }
  }
}
```

> Add your environment variables (API keys, etc.) inside the `.env` file.

#### 🌐 Server-Sent Events (SSE)

To run the server with Server-Sent Events (SSE) support, use the `--sse` flag:

```sh
node mcpServer.js --sse
```

or, with Docker:

```sh
docker run -it --rm --env-file=.env -p 3000:3000 netbox-mcp-server node mcpServer.js --sse
```

## 🛠️ Additional CLI commands

#### List tools

List descriptions and parameters from all generated tools with:

```sh
node index.js tools
```

Example:

```
Available Tools:

Workspace: acme-workspace
  Collection: useful-api
    list_all_customers
      Description: Retrieve a list of useful things.
      Parameters:
        - magic: The required magic power
        - limit: Number of results returned
        [...additional parameters...]
```

## ➕ Adding New Tools

Extend your MCP server with more tools easily:

1. Add new JS files to `tools/netbox-workspace/` for each NetBox API endpoint you want to expose.
2. Register each new tool in `tools/paths.js`.

## 💬 Questions & Support

For questions or support, please refer to the documentation in this repository or reach out to the project maintainer.

---

## 🆕 NetBox MCP Server Setup

### 1. Environment Variables
Add the following to your `.env` file in the project root:

```
# NetBox API Environment Variables
NETBOX_API_KEY=your_netbox_api_key_here
NETBOX_API_BASE_URL=https://your-netbox-instance/api/
```

### 2. Tool Registration
The NetBox tool `list-all-devices.js` is registered in `tools/paths.js` as:
```
'netbox-workspace/list-all-devices.js'
```

### 3. Usage in Cursor
- Start the MCP server via Cursor as described above.
- Use Cursor's MCP tool invocation to run the tool:
  - Tool name: `list_all_netbox_devices`
  - Parameter: `{ "limit": 10 }` (optional)

### 4. Testing
- You can also create a test script or use the MCP UI to invoke the tool and see results.
- Ensure your `.env` is set and your NetBox instance is reachable.

### 5. Adding More Tools
- Add new JS files to `tools/netbox-workspace/` for each NetBox API endpoint you want to expose.
- Register each new tool in `tools/paths.js`.