GeoNode MCP

MCP server for GeoNode 4.x and 5.x, with API compatibility resolved through configuration.

The server currently targets the GeoNode REST API exposed under /api/v2, which is still the documented API base for GeoNode 4.x and 5.x. The MCP configuration separates:

• GEONODE_VERSION: the GeoNode product version (4 or 5)
• GEONODE_API_VERSION: the REST API version to use (currently v2)

This keeps the MCP ready for future API changes without spreading version checks across every tool.

Features

• Search and inspect GeoNode resources
• Detect the most likely GeoNode/API compatibility settings from a URL
• Generate ready-to-paste MCP client configuration snippets from a URL
• Write the generated MCP client configuration directly into a local config file
• Verify that a written MCP config file is structurally correct and usable
• Bootstrap a complete MCP client setup in one call
• Resolve the groups associated with a specific user
• List and manage datasets, documents, maps, users, and groups
• Run safer bulk user workflows for group onboarding, password setup, ownership audit, and guarded deletion
• List categories, keywords, regions, and owners
• Centralized compatibility layer for GeoNode/API version mapping
• Local stdio execution for MCP clients such as Codex, Cursor, OpenCode, and Claude Code

Available Tools

The MCP server exposes the tools below. Tools that create, update, delete, write files, or set passwords require credentials with the matching GeoNode permissions. Bulk password and deletion workflows include explicit safety fields such as dry_run, confirm, and expected_count.

Instance and MCP Configuration

Tool	Function
geonode_detect_instance	Probes a GeoNode URL and recommends GEONODE_URL, GEONODE_VERSION, and GEONODE_API_VERSION settings.
geonode_generate_mcp_config	Generates a ready-to-use MCP client configuration snippet without writing files.
geonode_write_mcp_config	Writes a generated MCP client configuration to a supported local client config file.
geonode_verify_mcp_config	Validates that a written MCP config is structurally correct and can launch the server.
geonode_bootstrap_mcp_config	Runs detection, config generation, file writing, and optional verification in one workflow.

Search and Generic Resources

Tool	Function
geonode_search_resources	Searches GeoNode resources through the generic resources endpoint with pagination and filters.
geonode_search_metadata_text	Searches metadata text across selected fields and resource types, merging targeted API queries.
geonode_get_resource	Fetches details for a generic GeoNode resource by ID.

Datasets

Tool	Function
geonode_list_datasets	Lists datasets with pagination and optional search/filter parameters.
geonode_get_dataset	Fetches dataset details by ID.
geonode_create_dataset	Creates a dataset entry.
geonode_update_dataset	Updates dataset metadata.
geonode_delete_dataset	Deletes a dataset by ID.

Documents

Tool	Function
geonode_list_documents	Lists documents with pagination and optional search/filter parameters.
geonode_get_document	Fetches document details by ID.
geonode_create_document	Creates a document entry.
geonode_update_document	Updates document metadata.
geonode_delete_document	Deletes a document by ID.

Maps

Tool	Function
geonode_list_maps	Lists maps with pagination and optional search/filter parameters.
geonode_get_map	Fetches map details by ID.
geonode_create_map	Creates a map entry.
geonode_update_map	Updates map metadata.
geonode_delete_map	Deletes a map by ID.

Users and Groups

Tool	Function
geonode_list_users	Lists users by name, username, or email.
geonode_get_user	Fetches user details by ID.
geonode_get_user_groups	Resolves the groups associated with a user by ID or exact username.
geonode_update_user	Updates supported user fields, currently first name and last name.
geonode_list_groups	Lists GeoNode groups.
geonode_get_group	Fetches group details by ID.

User and Group Workflows

Tool	Function
geonode_create_group	Creates or reuses a GeoNode group by slug.
geonode_bulk_create_users	Creates or reuses users from structured JSON input and can set a shared password with explicit confirmation.
geonode_add_users_to_group	Adds existing users to a group and verifies membership after the update.
geonode_bulk_create_users_and_add_to_group	Creates or reuses a group and users, optionally sets passwords, and adds the users to the group.
geonode_count_user_owned_resources	Counts owned datasets, documents, maps, and dashboards for selected users using filter{owner.pk}.
geonode_find_group_users_by_resource_ownership	Splits group users into users with and without owned resources, with optional email-domain filtering.
geonode_delete_users_safely	Deletes only explicitly listed users after fail-closed safety checks for confirmation, group membership, staff status, and owned resources.

Catalog Lookups

Tool	Function
geonode_list_categories	Lists GeoNode categories.
geonode_list_keywords	Lists keywords, optionally filtered by search text.
geonode_list_regions	Lists regions, optionally filtered by name or code.
geonode_list_owners	Lists resource owners, optionally filtered by search text.

Compatibility

Supported today:

• GeoNode 4.x with API v2
• GeoNode 5.x with API v2

Default runtime values:

• GEONODE_VERSION=5
• GEONODE_API_VERSION=v2

Local Installation

Requirements

• Python 3.10+
• Access to a GeoNode instance
• GeoNode credentials if you need authenticated operations

1. Clone the repository

git clone <your-repo-url>
cd mcp-geonode-api

2. Create a virtual environment

python3 -m venv .venv
source .venv/bin/activate

3. Install the package locally

For normal usage:

pip install -e .

For development, including linting and tests:

pip install -e ".[dev]"

4. Set environment variables

export GEONODE_URL="https://your-geonode.example.com"
export GEONODE_USER="admin"
export GEONODE_PASSWORD="your-password"
export GEONODE_VERSION="5"
export GEONODE_API_VERSION="v2"

Optional override:

export GEONODE_API_BASE_PATH="/api/v2"

Use GEONODE_API_BASE_PATH only if your deployment exposes the API under a custom path.

5. Run the server locally

python -m geonode_mcp

This starts the MCP server over stdio, which is what local MCP clients expect.

Configuration Reference

Environment variables

• GEONODE_URL: GeoNode base URL, without a trailing slash preferred
• GEONODE_USER: username for Basic Auth
• GEONODE_PASSWORD: password for Basic Auth
• GEONODE_VERSION: GeoNode major version, currently 4 or 5
• GEONODE_API_VERSION: API version, currently v2
• GEONODE_API_BASE_PATH: optional explicit API path override

Recommended values

For most GeoNode 5 deployments:

GEONODE_VERSION=5
GEONODE_API_VERSION=v2

For most GeoNode 4 deployments:

GEONODE_VERSION=4
GEONODE_API_VERSION=v2

Detecting the Correct Version Settings

The MCP includes a discovery tool named geonode_detect_instance.

Its purpose is to inspect a GeoNode instance URL and suggest which values should be used for:

• GEONODE_URL
• GEONODE_VERSION
• GEONODE_API_VERSION

This is a best-effort detection flow. In practice:

• API version detection is usually reliable when /api/v2/resources/ is reachable
• exact GeoNode major version detection depends on whether the instance exposes version hints in HTML, headers, or static files

Tool name

geonode_detect_instance

Input parameters

• url: base URL of the GeoNode instance, or even a known API URL
• username: optional Basic Auth username for probing protected instances
• password: optional Basic Auth password for probing protected instances
• timeout: optional timeout in seconds
• response_format: json or markdown

Example call

{
  "url": "https://your-geonode.example.com",
  "response_format": "json"
}

You can also pass an API URL directly:

{
  "url": "https://your-geonode.example.com/api/v2/resources/",
  "response_format": "json"
}

Example response

{
  "normalized_base_url": "https://your-geonode.example.com",
  "detected_api_base_path": "/api/v2",
  "recommended_settings": {
    "GEONODE_URL": "https://your-geonode.example.com",
    "GEONODE_VERSION": "5",
    "GEONODE_API_VERSION": "v2"
  },
  "confidence": {
    "geonode_version": "medium",
    "api_version": "high"
  }
}

Recommended usage

1. Run geonode_detect_instance against the target URL.
2. Copy the returned recommended settings into your MCP client configuration.
3. If GEONODE_VERSION is returned as undetermined or null, keep the detected GEONODE_API_VERSION and confirm the GeoNode major version manually.

Looking Up a User's Groups

The MCP includes a dedicated tool named geonode_get_user_groups.

Use it when you need to answer questions such as:

• "Which group does user my-user belong to?"
• "List the groups for a given user"
• "Resolve user membership by username without manually browsing users and groups"

Tool name

geonode_get_user_groups

Input parameters

• user_id: optional user numeric ID
• username: optional exact username when the user ID is not known
• response_format: json or markdown

You must provide either user_id or username.

Example call by username

{
  "username": "my-user",
  "response_format": "json"
}

Example response

{
  "user": {
    "pk": 1317,
    "username": "my-user"
  },
  "groups": [
    {
      "pk": 59,
      "title": "GRUPO_ACOES_RS",
      "group": {
        "name": "ROLE_GRUPO_ACOES_RS"
      }
    }
  ]
}

Why this tool exists

Without this tool, answering "which group does this user belong to?" is unnecessarily awkward:

• geonode_list_users is for discovery, not exact membership lookup
• geonode_get_user does not expose group membership directly
• geonode_list_groups is not optimized for reverse lookup by user

geonode_get_user_groups solves that directly by:

1. resolving the user by exact username when needed
2. calling the user-to-groups endpoint
3. returning the membership list in one step

Generating Ready-to-Use MCP Client Config

The MCP also includes a helper tool named geonode_generate_mcp_config.

This tool combines:

• instance detection from the provided URL
• recommended GEONODE_* settings
• a ready-to-paste MCP snippet for one target client

Tool name

geonode_generate_mcp_config

Input parameters

• client: one of codex, cursor, opencode, claude_code
• url: base URL of the GeoNode instance, or a known API URL
• username: optional Basic Auth username
• password: optional Basic Auth password
• geonode_version: optional manual override
• api_version: optional manual override
• server_name: optional MCP server name, default geonode
• python_command: Python executable path used to start python -m geonode_mcp
• response_format: markdown or json

Example call

{
  "client": "cursor",
  "url": "https://your-geonode.example.com",
  "username": "admin",
  "password": "your-password",
  "python_command": "/path/to/mcp-geonode-api/.venv/bin/python",
  "response_format": "markdown"
}

Example usage flow

1. Run geonode_generate_mcp_config.
2. Copy the generated snippet into the config file suggested by the response.
3. If needed, replace GEONODE_PASSWORD with your preferred secret-management pattern.

When to use each tool

• Use geonode_detect_instance if you only want to inspect a GeoNode URL and understand the inferred compatibility.
• Use geonode_generate_mcp_config if you want the final client snippet immediately.
• Use geonode_write_mcp_config if you want the MCP to update the target config file for you.
• Use geonode_verify_mcp_config after writing to confirm the file and command are valid.
• Use geonode_bootstrap_mcp_config if you want the full flow in one step.

One-Step Bootstrap

The MCP also provides geonode_bootstrap_mcp_config.

This is the highest-level helper. It:

• detects the target GeoNode instance
• resolves the recommended GEONODE_* settings
• writes the client config file
• optionally verifies the final result

Tool name

geonode_bootstrap_mcp_config

Input parameters

• client: one of codex, cursor, opencode, claude_code
• url: base URL of the GeoNode instance, or a known API URL
• config_path: file to create or update
• username: optional Basic Auth username
• password: optional Basic Auth password
• geonode_version: optional manual override
• api_version: optional manual override
• server_name: optional MCP server name, default geonode
• python_command: Python executable path used to start python -m geonode_mcp
• create_parent_dirs: create missing parent directories automatically
• verify_after_write: validate the file after writing, default true
• response_format: markdown or json

Example call

{
  "client": "cursor",
  "url": "https://your-geonode.example.com",
  "config_path": "/Users/you/.cursor/mcp.json",
  "username": "admin",
  "password": "your-password",
  "python_command": "/path/to/mcp-geonode-api/.venv/bin/python",
  "verify_after_write": true,
  "response_format": "json"
}

Recommended default workflow

For most users, geonode_bootstrap_mcp_config should be the default choice.

Why the lower-level tools still exist

The other tools are still useful and should remain:

• geonode_detect_instance: best for diagnosis and understanding what the server exposes
• geonode_generate_mcp_config: best when you want to review the snippet before touching files
• geonode_write_mcp_config: best when writing should happen without verification, or when verification must be separated
• geonode_verify_mcp_config: best for CI, troubleshooting, or validating an already existing config file

So after bootstrap exists, the lower-level tools are still justified. They are not redundant; they support review, debugging, and partial workflows.

Writing MCP Client Config Files Automatically

The MCP also provides geonode_write_mcp_config.

This tool:

• detects the instance settings from the URL
• generates the correct client configuration
• writes or updates the target local config file

Tool name

geonode_write_mcp_config

Input parameters

• client: one of codex, cursor, opencode, claude_code
• url: base URL of the GeoNode instance, or a known API URL
• config_path: file to create or update
• username: optional Basic Auth username
• password: optional Basic Auth password
• geonode_version: optional manual override
• api_version: optional manual override
• server_name: optional MCP server name, default geonode
• python_command: Python executable path used to start python -m geonode_mcp
• create_parent_dirs: create missing parent directories automatically
• response_format: markdown or json

Example call

{
  "client": "cursor",
  "url": "https://your-geonode.example.com",
  "config_path": "/Users/you/.cursor/mcp.json",
  "username": "admin",
  "password": "your-password",
  "python_command": "/path/to/mcp-geonode-api/.venv/bin/python",
  "response_format": "markdown"
}

What it updates

• For cursor and claude_code, it updates the mcpServers entry for the selected server name.
• For opencode, it updates the mcp entry for the selected server name.
• For codex, it updates the matching [mcp_servers.<name>] and [mcp_servers.<name>.env] TOML blocks.

Recommended usage

1. For the fastest setup, use geonode_bootstrap_mcp_config.
2. If you want a staged flow, use geonode_generate_mcp_config, then geonode_write_mcp_config, then geonode_verify_mcp_config.
3. Re-run the relevant tool whenever the GeoNode URL, credentials, or Python path changes.

Verifying a Written MCP Config File

The MCP also provides geonode_verify_mcp_config.

This tool validates:

• that the target file exists
• that the expected server entry is present
• that the file shape matches the selected client
• that the configured executable exists
• that python -m geonode_mcp can at least import the package when the command matches that pattern

Tool name

geonode_verify_mcp_config

Input parameters

• client: one of codex, cursor, opencode, claude_code
• config_path: file to validate
• server_name: MCP server name to inspect, default geonode
• response_format: markdown or json

Example call

{
  "client": "cursor",
  "config_path": "/Users/you/.cursor/mcp.json",
  "server_name": "geonode",
  "response_format": "json"
}

Recommended usage flow

1. Run geonode_write_mcp_config.
2. Run geonode_verify_mcp_config.
3. If verification fails, inspect the returned checks and correct the command path, environment, or file location.

MCP Client Setup

The examples below assume:

• the repository lives at /path/to/mcp-geonode-api
• the virtual environment lives at /path/to/mcp-geonode-api/.venv

Adjust those paths to your machine.

Codex

If you want the MCP to generate this automatically, call geonode_generate_mcp_config with "client": "codex". If you want it to write the file directly, use geonode_write_mcp_config with config_path="~/.codex/config.toml".

OpenAI documents MCP configuration in ~/.codex/config.toml. The mcp_servers table is documented for Codex; the local stdio example below follows that same structure for this server.

File: ~/.codex/config.toml

[mcp_servers.geonode]
command = "/path/to/mcp-geonode-api/.venv/bin/python"
args = ["-m", "geonode_mcp"]

[mcp_servers.geonode.env]
GEONODE_URL = "https://your-geonode.example.com"
GEONODE_USER = "admin"
GEONODE_PASSWORD = "your-password"
GEONODE_VERSION = "5"
GEONODE_API_VERSION = "v2"

If you prefer a project-specific setup, keep the same command and environment values in the Codex configuration you use for that workspace.

Cursor

If you want the MCP to generate this automatically, call geonode_generate_mcp_config with "client": "cursor". If you want it to write the file directly, use geonode_write_mcp_config with config_path="~/.cursor/mcp.json" or a project .cursor/mcp.json.

Cursor supports MCP via mcp.json. You can configure it globally in ~/.cursor/mcp.json or per project in .cursor/mcp.json.

File: .cursor/mcp.json

{
  "mcpServers": {
    "geonode": {
      "command": "/path/to/mcp-geonode-api/.venv/bin/python",
      "args": ["-m", "geonode_mcp"],
      "env": {
        "GEONODE_URL": "https://your-geonode.example.com",
        "GEONODE_USER": "admin",
        "GEONODE_PASSWORD": "your-password",
        "GEONODE_VERSION": "5",
        "GEONODE_API_VERSION": "v2"
      }
    }
  }
}

You can also use Cursor variable interpolation if needed, for example ${workspaceFolder} or ${env:GEONODE_PASSWORD}.

OpenCode

If you want the MCP to generate this automatically, call geonode_generate_mcp_config with "client": "opencode". If you want it to write the file directly, use geonode_write_mcp_config with config_path="~/.config/opencode/opencode.json" or a project opencode.json.

OpenCode loads config from ~/.config/opencode/opencode.json globally or opencode.json in the project root.

File: opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "geonode": {
      "type": "local",
      "command": [
        "/path/to/mcp-geonode-api/.venv/bin/python",
        "-m",
        "geonode_mcp"
      ],
      "enabled": true,
      "environment": {
        "GEONODE_URL": "https://your-geonode.example.com",
        "GEONODE_USER": "admin",
        "GEONODE_PASSWORD": "your-password",
        "GEONODE_VERSION": "5",
        "GEONODE_API_VERSION": "v2"
      }
    }
  }
}

Claude Code

If you want the MCP to generate this automatically, call geonode_generate_mcp_config with "client": "claude_code". If you want it to write the file directly, use geonode_write_mcp_config with config_path=".mcp.json" or another Claude Code MCP file path.

Claude Code supports local stdio MCP servers directly from the CLI and can also store project-scoped configuration in .mcp.json.

Option 1: add it with the CLI

claude mcp add --transport stdio geonode \
  --env GEONODE_URL=https://your-geonode.example.com \
  --env GEONODE_USER=admin \
  --env GEONODE_PASSWORD=your-password \
  --env GEONODE_VERSION=5 \
  --env GEONODE_API_VERSION=v2 \
  -- /path/to/mcp-geonode-api/.venv/bin/python -m geonode_mcp

For a shared project configuration:

claude mcp add --transport stdio --scope project geonode \
  --env GEONODE_URL=https://your-geonode.example.com \
  --env GEONODE_USER=admin \
  --env GEONODE_PASSWORD=your-password \
  --env GEONODE_VERSION=5 \
  --env GEONODE_API_VERSION=v2 \
  -- /path/to/mcp-geonode-api/.venv/bin/python -m geonode_mcp

Option 2: configure .mcp.json manually

File: .mcp.json

{
  "mcpServers": {
    "geonode": {
      "command": "/path/to/mcp-geonode-api/.venv/bin/python",
      "args": ["-m", "geonode_mcp"],
      "env": {
        "GEONODE_URL": "https://your-geonode.example.com",
        "GEONODE_USER": "admin",
        "GEONODE_PASSWORD": "your-password",
        "GEONODE_VERSION": "5",
        "GEONODE_API_VERSION": "v2"
      }
    }
  }
}

Recommended Setup Strategy

Use this layout if you want stable local development:

1. Install the package in a project-local virtual environment.
2. Point your MCP client to that virtualenv Python executable.
3. Keep secrets in environment variables or client-side secret storage where possible.
4. Set GEONODE_VERSION explicitly even when using defaults.
5. Only override GEONODE_API_BASE_PATH if your deployment is non-standard.

Development

Run checks:

ruff check .
python3 -m mypy src
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest -q

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 is recommended if your machine has unrelated global pytest plugins installed.

Why Versioning Is Implemented This Way

GeoNode 4.x and 5.x still document the primary REST API under /api/v2. Because of that, this project does not map GeoNode product versions directly to a new REST prefix. Instead, it:

• reads the GeoNode version from configuration
• reads the API version from configuration
• resolves the actual route set through a compatibility layer

That design keeps the tool surface stable and makes future version support much easier to add.

Sources

• OpenAI Codex MCP docs: developers.openai.com/learn/docs-mcp
• Cursor MCP docs: docs.cursor.com/advanced/model-context-protocol
• Claude Code MCP docs: code.claude.com/docs/en/mcp
• OpenCode MCP docs: opencode.ai/docs/mcp-servers
• OpenCode config locations: opencode.ai/docs/config
• GeoNode developer API docs: docs.geonode.org/en/5.0.x/devel/api/usage/index.html