Python Alfresco MCP Server

How to use

Once you have the MCP server running, connect an MCP client such as Claude Desktop or MCP Inspector to perform operations against your Alfresco server. Start with a stdio transport for fastest local interactions, or use HTTP for web-based testing and SSE for real-time updates. Typical workflows include searching for documents, uploading new files, editing properties, and managing folders. Each tool is accessed through your MCP client, and the client will prompt you for any required parameters.

How to install

Prerequisites you need before installation:

• Python 3.10 or newer
• Alfresco Content Services (Community or Enterprise)

Install a modern tool runner to simplify running the MCP server. You can use UVX or UV. The recommended approach is UVX for automatic isolation and global availability.

Option A: UVX plan (recommended) — install and run the MCP server using UVX.

# Install UV (if not already installed)
pip install uv

# Install UVX via its script or package manager instructions, then run the MCP server
uvx python-alfresco-mcp-server --help

# Start the MCP server with STDIO transport (default)
uvx python-alfresco-mcp-server

# Start the MCP server with HTTP transport (optional)
uvx python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8003

# Start the MCP server with SSE transport (optional)
uvx python-alfresco-mcp-server --transport sse --host 127.0.0.1 --port 8001

Option B: UV plan (development) — run the MCP server via UV in a development setup.

uv run python-alfresco-mcp-server
uv run python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8003
uv run python-alfresco-mcp-server --transport sse --host 127.0.0.1 --port 8001

Option C: Traditional methods (pip/pipx) — install and run the MCP server using pip or pipx. After installation, start the server with the same transport options as above.

Environment configuration for Alfresco connection (examples shown here). Set these variables in your shell or a .env file, then start the MCP server.

# Linux/macOS
export ALFRESCO_URL="http://localhost:8080"
export ALFRESCO_USERNAME="admin"
export ALFRESCO_PASSWORD="admin"
export ALFRESCO_VERIFY_SSL="false"

# Windows PowerShell
$env:ALFRESCO_URL="http://localhost:8080"
$env:ALFRESCO_USERNAME="admin"
$env:ALFRESCO_PASSWORD="admin"
$env:ALFRESCO_VERIFY_SSL="false"

# Windows Command Prompt
set ALFRESCO_URL=http://localhost:8080
set ALFRESCO_USERNAME=admin
set ALFRESCO_PASSWORD=admin
set ALFRESCO_VERIFY_SSL=false

Additional setup and configuration

Alfresco must be running to interact with the MCP Server. If you do not have an Alfresco server, you can start a Community edition via Docker Compose. Ensure the container ports align with the MCP server configuration. The MCP server supports multiple transports (STDIO, HTTP, SSE) to suit your testing and production needs.

You can review and adjust the Alfresco connection through environment variables or a .env file to simplify deployment across development and production environments.

To test connectivity and capabilities, use Claude Desktop or MCP Inspector configured to point at the MCP server transport you selected (stdio or http). Claude Desktop will prompt you per tool when you first use them, granting access as needed.

Notes and quick start tips

For fast testing, start the MCP server with the stdio transport and connect Claude Desktop with the udp-stdio configuration. For web-service testing, use the HTTP transport and point your MCP Inspector to http://127.0.0.1:8003.

Security: consider enabling OAuth 2.1 in Enterprise deployments if your environment requires it, and ensure SSL verification settings match your Alfresco deployment.

Configuration snippet (example)

{
  "mcpServers": {
    "alfresco_stdio": {
      "type": "stdio",
      "name": "alfresco_stdio",
      "command": "uvx",
      "args": ["python-alfresco-mcp-server", "--transport", "stdio"]
    },
    "alfresco_stdio_uv": {
      "type": "stdio",
      "name": "alfresco_stdio_uv",
      "command": "uv",
      "args": ["run", "python-alfresco-mcp-server", "--transport", "stdio"]
    }
  }
}

MCP server configuration overview

The server exposes a set of 15 tools and supporting resources to interact with Alfresco Content Services, including full text search, advanced search, metadata search, CMIS-like queries, file uploads, downloads, and repository information. Use a client to perform these actions and adjust authentication and connection details as needed.

search_content

Search documents and folders by text with optional max results and node type filtering

advanced_search

Perform advanced searches using query language with filters and sort options

search_by_metadata

Query documents by metadata properties using operators such as equals and contains

cmis_search

Run CMIS SQL-like queries for complex content discovery

browse_repository

Browse repository folders and nodes by ID

repository_info

Get information about the repository, version, and modules

upload_document

Upload a new document with filename, base64 content, parent folder, and description

download_document

Download document content by node ID and save to disk

create_folder

Create a new folder under a parent node with a name and description

get_node_properties

Retrieve metadata for a given node

update_node_properties

Update metadata such as name, title, description, and author for a node

delete_node

Delete a node, with option for permanent removal

checkout_document

Check out a document for editing with optional download for editing

checkin_document

Check in after editing with a comment and version option

cancel_checkout

Cancel an active checkout to unlock a node