arcgis-portal-mcp

MCP server for ArcGIS Portal and ArcGIS Online. Lets AI assistants search content, query feature layers, manage features, handle content operations, and administer users and groups.

Built on the Model Context Protocol for integration with Claude Desktop, Cursor, VS Code Copilot, and other MCP clients.

Disclaimer: This is an independent open-source project. It is not affiliated with, endorsed by, or sponsored by Esri Inc. "ArcGIS" is a registered trademark of Esri.

Features

• Connect to any ArcGIS Enterprise Portal or ArcGIS Online
• Search for items (feature services, web maps, layers, dashboards)
• Inspect item metadata, tags, and descriptions
• List layers in a feature service with geometry types and counts
• Query features with attribute filters, spatial filters, field selection, and pagination
• Add, update, and delete features in hosted feature layers
• Manage content: update item properties, share/unshare, delete items, read web map definitions
• Manage users: list users, get detailed user profiles
• Manage groups: list groups, create groups, invite users
• Publish services: upload files and publish as hosted feature services
• Run geoprocessing: execute synchronous and asynchronous GP tasks
• Portal admin: system info, license management, usage statistics
• Batch operations: bulk delete, share, and update multiple items
• Health check portal system status (requires admin privileges)

Design Principles

• No arcgis Python package dependency: uses raw REST API calls via requests so you don't need to install the arcgis package
• Works with Enterprise Portal AND ArcGIS Online: same tools, same API
• Multiple auth methods: token, username/password (generateToken), client_credentials, and OAuth2
• Auto-connect: reads .env file on startup, no manual auth needed per session
• 2FA-friendly: works with Enterprise portals that require two-factor authentication (client_credentials, no browser)
• Self-signed cert friendly: handles Enterprise portals with self-signed certificates
• Hardened: SQL injection validation on WHERE clauses, XSS protection in OAuth callbacks, automatic retry with exponential backoff on transient failures

Installation

# From source
cd arcgis-portal-mcp
pip install -e .

# Or install from GitHub
pip install git+https://github.com/Asem-D/arcgis-portal-mcp.git

Windows users: pywin32 is installed automatically as a platform-specific dependency.

Configuration

.env File (recommended)

Create a .env file in the project root for automatic connection on startup. A template is provided:

cp .env.example .env
# Edit .env with your portal credentials

portal_url=https://gis.example.com/portal
# Option 1: Username/password (recommended for most users)
username=your-portal-username
password=your-portal-password
# Option 2: OAuth2 app credentials (app-level, limited permissions)
# oauth_client_id=your-oauth-app-client-id
# oauth_client_secret=your-oauth-app-client-secret

The server reads these on startup and connects automatically. If username + password are provided, it uses generateToken (user-level, full permissions). Otherwise, it falls back to client_credentials (app-level, limited). No manual connect_portal call needed.

Note: The .env file is gitignored. Never commit credentials. .env.example is safe to commit.

MCP Client Configuration

For MCP clients (Claude Desktop, Cursor, etc.), the simplest setup uses a .env file:

{
  "mcpServers": {
    "arcgis-portal": {
      "command": "python",
      "args": ["-m", "arcgis_portal_mcp.server"],
      "cwd": "/path/to/arcgis-portal-mcp"
    }
  }
}

The server auto-connects from .env in the working directory. No env vars needed in the MCP config.

Alternatively, pass credentials via MCP client env vars:

{
  "mcpServers": {
    "arcgis-portal": {
      "command": "python",
      "args": ["-m", "arcgis_portal_mcp.server"],
      "env": {
        "portal_url": "https://gis.example.com/portal",
        "username": "your-portal-username",
        "password": "your-portal-password"
      }
    }
  }
}

connect_portal Tool Parameters

The connect_portal tool accepts these auth_method values:

Usage

Connect and Search

User: Search for all feature services in my portal
Agent: [calls connect_portal, then search_content with item_type="Feature Service"]

Query a Layer

User: Show me the first 10 parcels from the cadastral layer
Agent: [calls list_layers to find the parcel layer, then query_features with limit=10]

Audit Users

User: Who are the administrators in our portal?
Agent: [calls list_users, filters by role]

Add Features

User: Add these 3 buildings to the infrastructure layer
Agent: [calls add_features with the feature service URL and JSON features]

Share a Web Map

User: Share item abc123 with the "Planning Team" group and the whole org
Agent: [calls share_item with org=true and groups=<planning-team-id>]

Read a Web Map

User: What basemap and layers are in this web map?
Agent: [calls get_item_data to read the web map JSON, summarizes basemap and operational layers]

Publish a Shapefile

User: Publish this shapefile as a hosted feature service
Agent: [calls upload_item to upload the .zip, then publish_from_item to create the service]

Run a Geoprocessing Task

User: Run the buffer analysis on the parcels layer with a 100m distance
Agent: [calls execute_gp_task with the GP service URL and input parameters]

Bulk Operations

User: Delete all my draft items
Agent: [calls search_content to find items, then batch_delete_items to remove them]

Portal Administration

User: How many licenses do we have left?
Agent: [calls list_licenses to show license allocation and usage]

Available Tools

Phase 1: Read-only (v0.1)

Phase 2: Feature CRUD, User/Group & Content Management (v0.2)

Phase 3: Publishing, Geoprocessing, Admin & Batch (v1.0)

Authentication Methods

Recommendation for Enterprise portals with 2FA: Use auto (.env with client_credentials). Token auth won't work because 2FA blocks token generation. The client_credentials flow uses app-level OAuth2, no browser, no 2FA, no user interaction.

For ArcGIS Online or portals without 2FA: Username/password auth via generateToken is the fastest for MCP. Place username and password in your .env file for auto-connect on startup.

For full user permissions: Use OAuth2 once to get a long-lived token, then pass it directly.

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check arcgis_portal_mcp/

License

MIT. See LICENSE.

Author

Asem Daaboul ([email protected])