Mcpjungle

🚀 🌳 MCPJungle 🌳

MCPJungle is a self-hosted MCP Gateway tailored for private AI agents. It serves as the single source-of-truth registry for all Model Context Protocol Servers within your organization. Developers can register and manage MCP servers and their tools centrally, while MCP Clients can discover and utilize these tools through a unified "Gateway" MCP Server.

MCPJungle is the only MCP Server your AI agents need to connect to!

🚀 Quick Start

Who should use MCPJungle?

1. Developers using MCP Clients like Claude & Cursor that need to access MCP servers for tool-calling.
2. Developers building production-grade AI Agents that require access to MCP servers with built-in security, privacy, and Access Control.
3. Organizations aiming to view and manage all MCP client-server interactions from a central location, hosted in their own datacenter 🔒.

Steps to Get Started

1. Start the server locally using docker compose:

curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.yaml
docker compose up -d

2. Register a simple MCP server in mcpjungle:
   • Download the client binary either using brew or from the Releases.

brew install mcpjungle/mcpjungle/mcpjungle

- Add the [context7](https://context7.com/) remote MCP server to mcpjungle.

mcpjungle register --name context7 --url https://mcp.context7.com/mcp

3. Connect to mcpjungle from Claude:
   • Add the following configuration in your Claude MCP Servers:

{
  "mcpServers": {
    "mcpjungle": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp",
        "--allow-http"
      ]
    }
  }
}

- Try asking Claude for the following:

Use context7 to get the documentation for `/lodash/lodash`

Claude will then attempt to call the context7__get-library-docs tool via MCPJungle, which will return the documentation for the Lodash library.

🎉 Congratulations! You have successfully registered a remote MCP server in MCPJungle and called one of its tools via Claude.

✨ Features

• Centralized registry for MCP servers in an organization.
• Allows developers to manage MCP servers and tools from a single place.
• Enables MCP Clients to discover and use tools through a unified gateway.
• Supports both Streamable HTTP-based and STDIO-based MCP servers.
• Provides access control and authentication features in production mode.
• Offers OpenTelemetry metrics for observability.

📦 Installation

⚠️ Important Note

MCPJungle is BETA software. We're actively working to make it production-ready. You can provide your feedback by starting a discussion in this repository.

MCPJungle is distributed as a stand-alone binary. You can 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 Note

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

MCPJungle also provides a Docker image, which is useful for running the registry server:

docker pull mcpjungle/mcpjungle

💻 Usage Examples

Server

Running mcpjungle server inside Docker

For local development, using docker compose is the recommended way:

# docker-compose.yaml is optimized for individuals running mcpjungle on their local machines for personal use.
# mcpjungle will run in `development` mode by default.
curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.yaml
docker compose up -d

# docker-compose.prod.yaml is optimized for orgs deploying mcpjungle on a remote server for multiple users.
# mcpjungle will run in `production` mode by default, which enables enterprise features.
curl -O https://raw.githubusercontent.com/mcpjungle/MCPJungle/refs/heads/main/docker-compose.prod.yaml
docker compose -f docker-compose.prod.yaml up -d

Verify the server is running:

curl http://localhost:8080/health

If you plan to register stdio-based MCP servers that rely on npx or uvx, use the stdio tagged docker image:

MCPJUNGLE_IMAGE_TAG=latest-stdio docker compose up -d

💡 Usage Tip

If you're using docker-compose.yaml, this is already the default image tag. You only need to specify the stdio image tag if you're using docker-compose.prod.yaml.

Running mcpjungle server directly on the host machine

mcpjungle start

The main registry server and MCP gateway will be accessible on port 8080 by default.

Database

By default, the mcpjungle server creates a SQLite DB in the current working directory. For production, you can supply a DSN for a Postgresql database:

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

# Run as container
docker run mcpjungle/mcpjungle:latest

# Or run directly
mcpjungle start

Client

Adding Streamable HTTP-based MCP servers

mcpjungle register --name calculator --description "Provides some basic math tools" --url http://127.0.0.1:8000/mcp

If using docker compose on non-Linux systems:

mcpjungle register --name calculator --description "Provides some basic math tools" --url http://host.docker.internal:8000/mcp

You can also use a configuration file:

cat ./calculator.json
{
  "name": "calculator",
  "transport": "streamable_http",
  "description": "Provides some basic math tools",
  "url": "http://127.0.0.1:8000/mcp"
}

mcpjungle register -c ./calculator.json

List tools, check usage, and invoke a tool:

mcpjungle list tools
mcpjungle usage calculator__multiply
mcpjungle invoke calculator__multiply --input '{"a": 100, "b": 50}'

Adding STDIO-based MCP servers

Create a configuration file, e.g., filesystem.json:

{
  "name": "filesystem",
  "transport": "stdio",
  "description": "filesystem mcp server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
}

Register the server:

mcpjungle register -c ./filesystem.json

Removing MCP servers

mcpjungle deregister calculator
mcpjungle deregister filesystem

Connect to mcpjungle from other MCP Clients

Claude

{
  "mcpServers": {
    "mcpjungle": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/mcp",
        "--allow-http"
      ]
    }
  }
}

Cursor

{
  "mcpServers": {
    "mcpjungle": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Enabling/Disabling Tools

# Disable a specific tool
mcpjungle disable context7__get-library-docs

# Re-enable a specific tool
mcpjungle enable context7__get-library-docs

# Disable all tools of a server
mcpjungle disable context7

# Re-enable all tools of a server
mcpjungle enable context7

Tool Groups

Creating a Tool Group

Create a configuration file, e.g., claude-tools-group.json:

{
  "name": "claude-tools",
  "description": "This group only contains tools for Claude Desktop to use",
  "included_tools": [
    "filesystem__read_file",
    "deepwiki__read_wiki_contents",
    "time__get_current_time"
  ]
}

Create the group:

mcpjungle create group -c ./claude-tools-group.json

Managing tool groups

# List all tool groups
mcpjungle list groups

# View details of a specific group
mcpjungle get group claude-tools

# Delete a group
mcpjungle delete group claude-tools

Authentication

mcpjungle register --name huggingface --description "HuggingFace MCP Server" --url https://huggingface.co/mcp --bearer-token <your-hf-api-token>

Enterprise features

Access Control

# Create a new MCP client
mcpjungle create mcp-client cursor-local --allow "calculator, github"

Configure Cursor to use the access token:

{
  "mcpServers": {
    "mcpjungle": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer 1YHf2LwE1LXtp5lW_vM-gmdYHlPHdqwnILitBhXE4Aw"
      }
    }
  }
}

OpenTelemetry

# Enable OpenTelemetry metrics
export OTEL_ENABLED=true

# Optionally, set additional attributes
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production

# Start the server
mcpjungle start

🔧 Technical Details

Limitations

1. MCPJungle doesn't maintain long-running connections to registered MCP Servers. A new connection is created for each tool call, which has performance overhead but ensures no memory leaks.
2. MCPJungle does not support OAuth flow for authentication. This is a work in progress.

📄 License

No license information provided in the original document.

Contributing 💻

We welcome contributions from the community!

• For contribution guidelines and standards, see CONTRIBUTION.md
• For development setup and technical details, see DEVELOPMENT.md

Join our Discord community to connect with other contributors and maintainers.