alfresco-mcp-lab

aborroy/alfresco-mcp-lab

3.3

If you are the rightful owner of alfresco-mcp-lab and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Model Context Protocol (MCP) server is designed to facilitate communication between clients and the Alfresco Content Services (ACS) using a standardized protocol.

Tools
2
Resources
0
Prompts
0

Alfresco MCP Lab

A reproducible lab to experiment with the Model Context Protocol (MCP) against Alfresco Community Edition using Docker.

Architecture

flowchart LR
  O("`OLLAMA
  local gpt-oss`")
  CIC("`CIC LiteLLM
  service claude`")
  CMD("`MCP CLIENT 
  CMD`")
  UI("`MCP CLIENT 
  UI`")
  S("`MCP SERVER
  community project`")
  A("`ALFRESCO
  Community`")

  CMD -- "8003" --> S
  S   -- "8080" --> A
  UI  -- "8003" --> S

  O -. "11434" .-> CMD
  CIC -. "443" .-> UI

Components

Prerequisites

  • Docker & Docker Compose
  • For the MCP Client CMD

    • Ollama running on the host with the gpt-oss model pulled (around 13 GB):

      brew install ollama   # macOS (or see ollama.com for your OS)
ollama pull gpt-oss
  • For the MCP Client UI
    • LITELLM_API_KEY in your environment (or in .env) for your chosen provider

Networking note host.docker.internal works out-of-the-box on Docker Desktop (macOS/Windows) On Linux, add extra_hosts: ["host.docker.internal:host-gateway"] to services that must reach the host (e.g., to call Ollama running on the host)

Quick start

Bring up Alfresco and MCP Server:

docker compose up --build

Once started:

About compose.yaml

This repo compose.yaml includes sub-stacks:

include:
  - mcp-server/compose.yaml
  - alfresco/compose.yaml

If your Compose version doesn’t support include, run with multiple files:

docker compose -f alfresco/compose.yaml -f mcp-server/compose.yaml up --build

MCP client (CLI)

This client uses a local LLM (gpt-oss) via Ollama

  1. Verify Ollama and model:

    ollama list
# Expect something like:
# gpt-oss:latest   ...   13 GB

  2. Run the CLI:

    cd mcp-client-cmd
docker compose run --rm mcp-client

  3. Try a prompt:

    Search Alfresco for documents containing "budget", return at most 5 results.

Helpful prompts from Steve Reiner: https://github.com/stevereiner/python-alfresco-mcp-server/blob/main/prompts-for-claude.md

MCP client (UI)

  1. Switch to the MCP Client UI folder
cd mcp-client-ui

  1. Create your .env from the example and set LiteLLM + MCP/ACS endpoints.

    • macOS/Linux:

      cp .env.example .env

    • Windows (PowerShell):

      Copy-Item .env.example .env

    Example .env:

    # LiteLLM (replace with your provider/base/model)
LITELLM_API_KEY=YOUR_API_KEY
LITELLM_API_BASE=https://api.your-provider.example/v1
LITELLM_MODEL=anthropic/claude-3-5-sonnet

# MCP Server
MCP_URL=http://host.docker.internal:8003/mcp

# Logging
LOG_LEVEL=INFO

    On Linux, if the UI container can’t reach the host, add:

    extra_hosts:
  - "host.docker.internal:host-gateway"

  2. Start the UI:

    docker compose up --build

  3. Open http://localhost:8000 and chat

MCP UI Sample Prompt

You may try a more complex prompt, performing actions in Alfresco Repository and following a complete workflow:

Let's test a complete document management workflow:

1. Create a folder called "Project_Alpha"
2. Upload a document called "requirements.md" to that folder with some project requirements content
3. Get the document properties to verify it was created correctly
4. Update the document properties to add a title and description
5. Checkout the document for editing
6. Checkin the document as major version with appropriate comments
7. Search for documents containing "requirements" using basic search (AFTS full-text)
8. Try advanced search with date filters to find the same document (AFTS with filters)
9. Use metadata search to find it by title property (AFTS property search)
10. Use CMIS search with SQL query to find it by name (CMIS SQL)
11. Download the document to verify content integrity

Walk me through each step and confirm success before moving to the next.

Ports summary

  • Alfresco (ACS): 8080 (/alfresco)
  • MCP Server: 8003 (/mcp)
  • MCP UI (Chainlit): 8000
  • Ollama: 11434
  • LiteLLM: 443

Building everything yourself

See for from-scratch builds and deeper configuration

MCP Server tools for Alfresco

The mcp-server/ folder wires the lab to python-alfresco-mcp-server (built on FastMCP 2.0). It exposes a focused toolset for content search + document lifecycle against Alfresco. In the latest 1.1 line, the server documents the following capabilities and transports (STDIO, HTTP, SSE)

Tools

  • Search Content: Full-text search over content and properties, basic wildcards
  • Advanced Search (AFTS): AFTS query language with date filters, sort, field targeting (tool name appears as the AFTS/“advanced search” tool in docs)
  • Metadata Search: Property predicates (equals/contains/ranges) over node metadata
  • CMIS (SQL-like) Search: CMIS query for complex discovery
  • Upload: Create a new document with content
  • Download: Fetch document content by id/path
  • Check-out / Check-in / Cancel check-out: Working-copy flow and new versions (major/minor with comments)
  • Create Folder: Create folder by parent id/path
  • Folder Browse: List children + basic metadata
  • Delete Node: Trash (or permanent) delete for documents/folders
  • Get / Set Properties: Read/update node properties (incl. name)
  • Repository Info (also exposed as a Resource): Edition, version, status and module configuration

Model Context Protocol (MCP) — spec & SDKs

  • Spec & Concepts: Tools, Resources, Prompts, transports, and protocol revisions are covered in the official docs/spec. Start here for how tools are defined and invoked (Model Context Protocol)
  • Official SDKs: TypeScript, Python, Java, Go, Kotlin, Swift, C#, Ruby, Rust. Each supports building servers/clients with the same core semantics (Model Context Protocol)

Best ways to implement an Alfresco MCP server

  1. Python + FastMCP (used for this lab) Fast to stand up, battle-tested with Alfresco via python-alfresco-mcp-server, and supports STDIO/HTTP/SSE out of the box. Ideal for demos and production pilots. (GitHub)

  2. Java + Spring AI (MCP Java SDK + Spring Boot starters) First-class Java SDK maintained with Spring; Spring AI adds auto-config, starters, and both client/server support. Best fit for teams standardizing on JVM/Spring. (MCP, Spring AI)

  3. TypeScript (official SDK) Great if your stack is Node/TS or you want to align with Claude Desktop/TS examples. Same protocol model, rich Zod schemas. (Model Context Protocol)

You can also target Go/Kotlin/Swift/C#/Ruby/Rust via the official SDKs when platform constraints or existing services make those a better fit

Credits & acknowledgements