Installation

MCPJungle is shipped as a stand-alone binary.

You can either download it from the Releases Page or use Homebrew to install it:

brew install mcpjungle/mcpjungle/mcpjungle

Verify your installation by running

mcpjungle version

[!IMPORTANT] On MacOS, you will have to use homebrew because the compiled binary is not Notarized yet.

MCPJungle provides a Docker image which is useful for running the registry server (more about it later).

docker pull ghcr.io/mcpjungle/mcpjungle

Running inside Docker

For running the MCPJungle server locally, docker compose is the recommended way: ```shell

docker-compose.yaml is optimized for individuals running mcpjungle on their local machines for personal use.

docker-compose.prod.yaml is optimized for orgs deploying mcpjungle on a remote server for multiple users.

Or use the enterprise-mode docker compose file as described above

docker compose -f docker-compose.prod.yaml up -d

By default, mcpjungle server runs in `development` mode which is ideal for individuals running it locally.

In Enterprise mode, the server enforces stricter security policies and will provide additional features like Authentication, ACLs, observability and more.

After starting the server in enterprise mode, you must initialize it by running the following command on your client machine:

This will create an admin user in the server and store its API access token in your home directory (~/.mcpjungle.conf).

You can then use the mcpjungle cli to make authenticated requests to the server.

Quickstart

This quickstart guide will show you how to: 1. Start the mcpjungle server locally using docker compose 2. Add an MCP server in mcpjungle 3. Connect your Claude Desktop to mcpjungle to access your MCP tools

Usage

MCPJungle has a Client-Server architecture and the binary lets you run both the Server and the Client.

Check tool usage

mcpjungle usage calculator__multiply

You can supply the database DSN as an env var

export DATABASE_URL=postgres://admin:root@localhost:5432/mcpjungle_db

#run as container docker run ghcr.io/mcpjungle/mcpjungle:latest

host is mandatory if you're using postgres-specific env vars

export POSTGRES_HOST=localhost export POSTGRES_PORT=5432

export POSTGRES_USER=admin export POSTGRES_USER_FILE=/path/to/user-file

export POSTGRES_PASSWORD=secret export POSTGRES_PASSWORD_FILE=/path/to/password-file

export POSTGRES_DB=mcpjungle_db export POSTGRES_DB_FILE=/path/to/db-file

mcpjungle start ```

Save the JSON configuration to a file (e.g., filesystem.json)

mcpjungle register -c ./filesystem.json

The config file format for registering a STDIO-based MCP server is:

You can also watch a quick video on [How to register a STDIO-based MCP server](https://youtu.be/YqHiuexR5fw).

> [!TIP]
> If your STDIO server fails or throws errors for some reason, check the mcpjungle server's logs to view its `stderr` output.

#### Environment variables in JSON config files

When you use a JSON config file to register a mcp server or create other entities like tol groups, the CLI can resolve environment variable placeholders in string values before sending the request to the server.

- Only placeholders written as `${VAR_NAME}` are resolved.
- Placeholders can appear anywhere inside a string value, for example `prefix-${VAR_NAME}-suffix`.
- Resolution happens in the CLI process, so the environment variable must be available where you run the command.
- If a referenced environment variable is not set, the command fails with an error.
- This applies to string fields across the JSON config, including nested objects and string arrays.

Example MCP server config:

Example STDIO config:

**Caveat** ⚠️

When running mcpjungle inside Docker, you need some extra configuration to run the `filesystem` mcp server.

By default, mcpjungle inside container does not have access to your host filesystem.

So you must:
- mount the host directory you want to access as a volume in the container
- specify the mount path as the directory in the filesystem mcp server command args

The `docker-compose.yaml` provided by mcpjungle mounts the current working directory as `/host` in the container.

So you can use the following configuration for the filesystem mcp server:

Then, the mcp has access to `/host`, ie, the current working directory on your host machine.

See [DEVELOPMENT.md](./DEVELOPMENT.md#docker-filesystem-access) for more details.

#### Running CLI commands from a Docker or Kubernetes deployment
If your MCPJungle server is running in a remote Docker container or Kubernetes cluster, you can also execute the `mcpjungle` binary directly inside the container:

[!NOTE] The standard image does not include a shell. Run /mcpjungle directly via docker exec or kubectl exec.

This is useful for running CLI commands from the same environment where the server is running.

Configuring a custom registry URL

By default, the CLI connects to the mcpjungle server at http://127.0.0.1:8000.

If your server is running on a different host or port (e.g., a remote deployment), you can configure the registry URL in two ways:

Option 1: Use the --registry flag

mcpjungle --registry http://my-server:9000 list tools

Option 2: Set it in the config file

Create or edit ~/.mcpjungle.conf:

registry_url: http://my-server:9000

This avoids having to pass the --registry flag on every command.

you can also specify the server mode as environment variable (valid values are `development` and `enterprise`)

export SERVER_MODE=enterprise mcpjungle start

Create user from config file

mcpjungle create user --conf /path/to/user-config.json

The config file format for creating a user is similar to that of an MCP client:

Again, when using the config file, you must provide a custom access token.

Just like other JSON config files in MCPJungle, user config files also support ${VAR_NAME} placeholders in string fields.

optionally, set additional attributes to be added to all metrics

export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=enterprise

Integration with other MCP Clients

Assuming that MCPJungle is running on http://localhost:8080, use the following configurations to connect to it: