Alfresco MCP Server (IPR Fork)

A Model Context Protocol (MCP) server for Alfresco providing tools via the Alfresco REST API.
This fork includes fixes for production deployment with self-signed certificates and network-wide access.

Features

• Ticket-based Authentication: Uses Alfresco authentication tickets
• Multiple Transport Modes: Supports stdio, SSE, and HTTP
• Docker Support: Configurable container for all transport modes
• Self-Signed TLS Support: Works with Alfresco instances using self-signed certificates
• Network-Wide Binding: Ready to serve across the network out of the box

Prerequisites

• Python 3.11+
• Alfresco instance (with REST API accessible)
• Alfresco authentication ticket

Installation

Local Setup

1. Clone or create the project directory with all files

2. Install dependencies:

python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

3. Set environment variable:

export ALFRESCO_HOST=http://your-alfresco-host:8080

Testing Locally with MCP Inspector

1. Install MCP Inspector (only once)

npm install -g @modelcontextprotocol/inspector

2. Run the server with Inspector

Start the server using streamable-http transport mode

python alfresco_mcp_server.py --transport http --host 127.0.0.1 --port 8003

Start the MCP Inspector

mcp-inspector --config ./mcp.json

Getting an Alfresco Ticket

You need to authenticate with Alfresco first to get a ticket. You can do this via:

curl -X POST "http://localhost:8080/alfresco/api/-default-/public/authentication/versions/1/tickets" \
  -H "Content-Type: application/json" \
  -d '{"userId":"admin","password":"admin"}'

This returns a JSON response with an id field containing your ticket.

Note for self-signed certificates: Add -k (insecure) flag:

curl -k -X POST "https://your-alfresco-host/alfresco/api/-default-/public/authentication/versions/1/tickets" \
  -H "Content-Type: application/json" \
  -d '{"userId":"admin","password":"admin"}'

Ticket Expiry Handling

When the Alfresco ticket expires during a session, the MCP server now returns a helpful error message with the exact curl command to generate a fresh ticket, dynamically populated with your Alfresco host URL. Simply run the suggested command and call set_ticket with the new ticket value.

Running with FastMCP Directly

STDIO Mode (default)

python alfresco_mcp_server.py

HTTP Mode

fastmcp dev alfresco_mcp_server.py --transport http --port 8003

SSE Mode

fastmcp dev alfresco_mcp_server.py --transport sse --port 8003

Docker Usage

Build the Image

docker build -t alfresco-mcp-server .

Run in Different Modes

STDIO Mode (default)

docker run -it --rm \
  -e ALFRESCO_HOST=http://your-alfresco-host:8080 \
  alfresco-mcp-server

HTTP Mode

docker run -d --rm \
  -e ALFRESCO_HOST=http://your-alfresco-host:8080 \
  -e TRANSPORT_MODE=http \
  -e HTTP=8003 \
  -p 8003:8003 \
  alfresco-mcp-server

SSE Mode

docker run -d --rm \
  -e ALFRESCO_HOST=http://your-alfresco-host:8080 \
  -e TRANSPORT_MODE=sse \
  -e HTTP=8003 \
  -p 8003:8003 \
  alfresco-mcp-server

Docker Compose Example

services:
  alfresco-mcp:
    build: .
    environment:
      - ALFRESCO_HOST=http://alfresco:8080
      - TRANSPORT_MODE=http  # or sse, stdio
      - HTTP=8003
    ports:
      - "8003:8003"  # Only needed for http/sse modes

Environment Variables

Variable	Description	Default
ALFRESCO_HOST	Base URL of Alfresco instance	http://localhost:8080
TRANSPORT_MODE	Transport mode (stdio/http/sse)	stdio
HTTP	Port for HTTP/SSE modes	8003

Deployment Notes (IPR Fork)

Making the Server Accessible Network-Wide

By default, the MCP server binds to 0.0.0.0 when running in HTTP/SSE mode inside Docker (see Dockerfile entrypoint). This ensures the server is reachable from any machine on the network.

Key changes for network access:

1. Docker port mapping: The compose.yaml exposes the MCP port (default 8003) to the host, making it accessible at http://<host-ip>:8003.
2. Bind to all interfaces: The entrypoint script passes --host 0.0.0.0 so the server listens on all network interfaces.
3. MCP client configuration: Point your MCP client to http://<server-ip>:8003/mcp (streamable HTTP transport).

Self-Signed Certificate Handling

If your Alfresco instance uses HTTPS with a self-signed certificate (common in internal/enterprise networks), you will encounter TLS verification errors. The following fixes are in place:

1. Server-side (httpx client): The _client() function in alfresco_mcp_server.py uses verify=False to skip SSL certificate verification when making requests to the Alfresco REST API. This is safe in internal network environments where the certificate authority is not publicly trusted.

2. Client-side (curl commands): All curl examples in the ticket error guidance include the -k flag to bypass self-signed cert verification.

Why this is needed: Self-signed certificates are common in on-premise Alfresco deployments where IT manages their own CA. Without this fix, all API calls fail with SSLCertVerificationError, making the MCP server unusable.

Ticket Error Handling Improvement

The _missing_ticket_message() function was enhanced to:

• Dynamically include the configured ALFRESCO_HOST in the suggested curl command
• Provide a ready-to-use curl command with -k flag for self-signed cert environments
• Guide the user to call set_ticket with the new ticket value—no server restart required

Publishing in Docker Hub

Create/use a builder

docker buildx create --name mcp-builder --use
docker buildx inspect --bootstrap

Build & push (multi-arch) with SBOM + provenance + OCI annotations

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --pull \
  --provenance=mode=max \
  --sbom=true \
  --annotation "index:org.opencontainers.image.source=https://github.com/angelborroy/alfresco-mcp-server" \
  --annotation "index:org.opencontainers.image.description=Alfresco MCP Server" \
  -t angelborroy/alfresco-mcp-server:1.0.0 \
  -t angelborroy/alfresco-mcp-server:latest \
  --metadata-file build-metadata.json \
  --push .

Cleanup

docker buildx rm mcp-builder