Python Alfresco MCP Server

🚀 Python Alfresco MCP Server v1.1

A full - featured MCP server for Alfresco in search and content management areas

🚀 Quick Start

The Python Alfresco MCP Server v1.1 is a powerful tool for Alfresco content management and search. Built with FastMCP 2.0, it offers a wide range of content management and search tools, as well as comprehensive documentation and examples.

✨ Features

Content Management and Search Tools

• Search Tools:
  • Full Text Search (search_content): Basic content search with wildcard support.
  • Advanced Search: Utilize AFTS query language with date filters, sorting, and field targeting.
  • Metadata Search: Conduct property - based queries with operators like equals, contains, and date ranges.
  • CMIS Search: Perform SQL - like queries for complex content discovery.
• Document Lifecycle: Support for upload, download, check - in, checkout, and cancel checkout operations.
• Version Management: Create major/minor versions with comments.
• Folder Operations: Create and delete folder nodes.
• Property Management: Get and set document/folder properties and names.
• Node Operations: Delete nodes (documents and folders) either to trash or permanently.
• Repository Info: Retrieve repository status, version, edition (Community or Enterprise), and module configuration.

MCP Architecture

• FastMCP 2.0 Framework: A modern, high - performance MCP server implementation.
• Multiple Transports:
  • STDIO (direct MCP protocol): Default and fastest option.
  • HTTP (RESTful API): Ideal for web services and testing.
  • SSE (Server - Sent Events): Enable real - time streaming updates.
• Enterprise Security: Optional OAuth 2.1 support.
• Type Safety: Full Pydantic v2 models.
• In - Memory Testing: Facilitate faster client testing.
• Configuration: Support for environment variables and .env files.

Alfresco Integration

Compatible with both Alfresco Community (tested) and Enterprise editions.

📦 Installation

Install Python

You need Python 3.10+ installed. Download the latest 3.13.x version from Python.org Downloads.

UV/UVX Setup (Recommended)

UV is a modern Python package manager written in Rust that provides uv (package manager) and uvx (tool runner). It's much faster than pip due to its compiled nature and optimized dependency resolution.

# Install UV (provides both uv and uvx commands)
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux  
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via pip if you prefer
pip install uv

# Verify installation (both commands should work)
uv --version
uvx --version

UV Reference Links:

• UV Installation Guide - Official installation instructions and platform - specific options.
• UV Documentation - Complete UV documentation, guides, and advanced usage.

Option A: UVX - Modern Tool Runner (Recommended for Users)

UVX is UV's tool runner, similar to pipx but faster and more modern. It automatically handles isolation and global availability.

# Install python-alfresco-mcp-server with uvx (after UV/UVX setup above)
uvx python-alfresco-mcp-server --help

# This tests that installation worked - UVX automatically installs packages on first use!

Option B: UV - Modern Package Manager (Recommended for Development)

# Install and run from PyPI (fastest for users)
uv tool install python-alfresco-mcp-server
uv tool run python-alfresco-mcp-server --help  # Tests that installation worked

# Or install from source (for development)
git clone https://github.com/stevereiner/python-alfresco-mcp-server.git
cd python-alfresco-mcp-server
uv run python-alfresco-mcp-server --help  # Tests that installation worked

Option C: Traditional Methods (pip and pipx)

For traditional Python package management approaches, see the Installation with pip and pipx.

Source Installation (For Development)

# 1. Clone the repository
git clone https://github.com/stevereiner/python-alfresco-mcp-server.git
cd python-alfresco-mcp-server

# 2. UV handles everything automatically - run immediately!
uv run python-alfresco-mcp-server --help  # Tests that installation worked

# Or install dependencies explicitly for development:
uv sync                    # Basic dependencies
uv sync --extra dev        # With development tools  
uv sync --extra test       # With testing tools
uv sync --extra all        # Everything

Configure Alfresco Connection

Option 1: Environment Variables

# Linux/Mac
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

Option 2: .env file (recommended - cross - platform):

# Copy sample-dot-env.txt to .env and customize
# Linux/macOS
cp sample-dot-env.txt .env

# Windows
copy sample-dot-env.txt .env

# Edit .env file with your settings
ALFRESCO_URL=http://localhost:8080
ALFRESCO_USERNAME=admin
ALFRESCO_PASSWORD=admin
ALFRESCO_VERIFY_SSL=false

⚠️ Important Note

The .env file is not checked into git for security. Use sample-dot-env.txt as a template.

📖 See Configuration Guide for complete setup options

Alfresco Installation

If you don't have an Alfresco server installed, you can get a docker for the Community version from Github.

git clone https://github.com/Alfresco/acs-deployment.git

Move to Docker Compose directory

cd acs-deployment/docker-compose

Edit community-compose.yaml

• Note: you will likely need to comment out activemq ports other than 8161.

   ports:
   - "8161:8161" # Web Console
   #- "5672:5672" # AMQP
   #- "61616:61616" # OpenWire
   #- "61613:61613" # STOMP

Start Alfresco with Docker Compose

docker-compose -f community-compose.yaml up

💻 Usage Examples

MCP Server Startup

With UVX (Recommended - Automatic isolation and global availability):

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

# HTTP transport for web services (matches MCP Inspector)
uvx python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8003

# SSE transport for real-time streaming  
uvx python-alfresco-mcp-server --transport sse --host 127.0.0.1 --port 8001

With UV (For development or source installations):

# Run MCP server with STDIO transport (default)
uv run python-alfresco-mcp-server

# HTTP transport for web services (matches MCP Inspector)
uv run python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8003

# SSE transport for real-time streaming  
uv run python-alfresco-mcp-server --transport sse --host 127.0.0.1 --port 8001

With Traditional Methods (pip/pipx): See the Installation with pip and pipx for pip and pipx usage instructions.

MCP Client Setup and Use

🤖 Claude Desktop for Windows (tested) and MacOS (not tested)

📖 Complete Setup Guide: Claude Desktop Setup Guide

📥 Download Claude Desktop (Free and Pro versions):

• Download Claude Desktop - Official Anthropic download page.
• Available for Windows and macOS only (no Linux version).
• Free tier includes full MCP support and Claude Sonnet 4 access with limits, older Claude models (Claude Opus 4 only in Pro).

🔧 Claude Desktop Configuration by Installation Method:

1. UVX (Recommended - Modern tool runner):

{
  "command": "uvx",
  "args": ["python-alfresco-mcp-server", "--transport", "stdio"]
}

• Sample Config Files:
  • Windows:
  • macOS:

2. UV (Development or source installations):

{
  "command": "uv",
  "args": ["run", "python-alfresco-mcp-server", "--transport", "stdio"],
  "cwd": "C:\\path\\to\\python-alfresco-mcp-server"
}

• Sample Config Files:
  • Windows:
  • macOS:

3. Traditional Methods (pipx/pip): For traditional installation methods, see the Installation with pip and pipx.

🔐 Tool - by - Tool Permission System: Claude Desktop will prompt you individually for each tool on first use. You can choose "Allow once" or "Always allow".

Using the Tools:

• Chat naturally about document management and search tasks.
• Mention "Alfresco" to ensure the MCP server is used.
• Use tool - related keywords.
• Follow - up prompts will use previous context.

Example 1: Document Management

1. Upload a simple text document: "Please create a file called 'claude_test_doc-25 07 25 101 0 AM.txt' in the repository shared folder with this content: 'This is a test document created by Claude via MCP.' description 'Test document uploaded via Claude MCP'"
2. Update properties: "Set the description property of this document to 'my desc'"
3. Check out the document
4. Cancel checkout
5. Check out again
6. Check in as a major version
7. Download the document
8. Upload a second document from "C:\1 sample files\cmispress.pdf"

Example 2: Search Operations "With Alfresco please test all 3 search methods and CMIS query:"

• Basic search for "txt" documents, return max 10.
• Advanced search for documents created after 2024 - 01 - 01, return max 25.
• Metadata search for documents where cm:title contains "test", limit to 50.
• CMIS search to find all txt documents, limit to 50.

More Examples: Create Folder, Browse Folders, Get Repository Info

• "Create a folder called '25 07 25 01 18 am' in shared folder"
• "List docs and folders in shared folder" (will use -shared-)
• "Can you show me what's in my Alfresco home directory?" (will use browse_repository -my-)
• "Get info on Alfresco" (will use repository_info tool)

Chat Box Buttons

• Use the Search and tools button (two horizontal lines with circles icon) in the chat box and choose "python-alfresco-mcp-server" to enable/disable all tools or individual tools.
• Click the + Button → "Add from alfresco" for quick access to resources and prompts.

Search and Analyze Prompt:

• Provides a form with a query field for full - text search.
• Analysis types: summary, detailed, trends, or compliance.
• Generates template text to copy/paste into chat for editing.

Repository Info Resource (and Tool):

• Provides status information in text format for viewing or copying.

Examples:

• See for examples testing the tools.

🔍 MCP Inspector (Development/Testing)

📖 Setup Guide: Complete MCP Inspector setup and connection instructions in MCP Inspector Setup Guide

📥 Install MCP Inspector:

• Prerequisites: Requires Node.js 18+ - Download from nodejs.org
• Install Command: npm install -g @modelcontextprotocol/inspector
• Or run directly: npx @modelcontextprotocol/inspector (no global install needed)

Working Method (Recommended):

1. Start MCP Server with HTTP transport:

# With UVX (recommended)
uvx python-alfresco-mcp-server --transport http --port 8003

# With UV (development)
uv run python-alfresco-mcp-server --transport http --port 8003

# Traditional methods - see Traditional Installation Guide

2. Start MCP Inspector with config: UVX Installation (Recommended):

# Start with stdio transport
npx @modelcontextprotocol/inspector --config mcp-inspector-stdio-uvx-config.json --server python-alfresco-mcp-server

# Start with http transport  
npx @modelcontextprotocol/inspector --config mcp-inspector-http-uvx-config.json --server python-alfresco-mcp-server

UV Installation (Development):

# From project directory where config files exist
npx @modelcontextprotocol/inspector --config mcp-inspector-stdio-uv-config.json --server python-alfresco-mcp-server  # stdio transport
npx @modelcontextprotocol/inspector --config mcp-inspector-http-uv-config.json --server python-alfresco-mcp-server   # http transport

Traditional Methods (pipx/pip): See the Installation with pip and pipx for pipx and pip configuration options.

3. Open browser with pre - filled token:

• Use the URL provided in the output (includes authentication token).
• Example: http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>

🛠️ Available Tools (15 Total)

🔍 Search Tools (4)

🛠️ Core Tools (11)

📖 See API Reference for detailed tool documentation

📊 Available Resources

Repository Information

The repository_info resource provides:

• Repository Details: ID, edition (Community/Enterprise), version information.
• License Information: Issued/expires dates, remaining days, license holder, entitlements.
• System Status: Read - only mode, audit enabled, quick share, thumbnail generation.
• Installed Modules: Up to 10 modules with ID, title, version, and installation state.

📖 See API Reference for detailed resource documentation

🎯 Available Prompts

Search and Analyze Prompt

The search_and_analyze prompt provides:

• Interactive Form: A user - friendly interface with a query input field.
• Analysis Options: Choose from summary, detailed analysis, trends, or compliance reporting.
• Template Generation: Creates copyable template text for chat conversations.
• Query Assistance: Helps users structure effective search queries.
• Multiple Search Types: Integrates with all 4 search tools (content, advanced, metadata, CMIS).

📖 See API Reference for detailed prompt documentation

🔧 Configuration Options

⚙️ See Configuration Guide for deployment options

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                   MCP Clients                       │
│  Claude Desktop │ MCP Inspector │ Cursor │ Claude   │
│     Code │ n8n │ LangFlow │ Custom MCP Client App   │
└─────────────────┬───────────────────────────────────┘
                  │ stdio/HTTP/SSE
┌─────────────────▼───────────────────────────────────┐
│             FastMCP 2.0 MCP Server                  │
│  ┌─────────────┬─────────────┬─────────────────┐    │
│  │ MCP Tools   │ MCP         │ HTTP/SSE API    │    │
│  │ (15 total)  │ Resources   │                 │    │
│  │             │ MCP Prompts │                 │    │
│  └─────────────┴─────────────┴─────────────────┘    │
└─────────────────┬───────────────────────────────────┘
                  │ python-alfresco-api
┌─────────────────▼───────────────────────────────────┐
│            Alfresco Content Services                │
│         (Community/Enterprise Edition)              │
└─────────────────────────────────────────────────────┘

🧪 Testing & Quality

Test Suite Overview

• 143 Total Tests: 100% passed - Comprehensive coverage of all functionality.
• 122 Unit Tests: 100% passed - Validate core functionality with mocking.
• 21 Integration Tests: 100% passed - Conduct live server testing for search, upload, download, and document lifecycle operations.
• Performance Validated: Search operations complete in <1s, support concurrent operations and resource access.

Coverage Report (Post - Cleanup)

• Overall Coverage: 51% (1,829 statements tested).
• FastMCP 2.0 Core: Well - tested with comprehensive unit coverage.
• Configuration Module: 93% coverage - Fully tested.
• Package Initialization: 100% coverage (5/5 lines) - Complete.

Run Tests

# Run full test suite
pytest

# Run with coverage report
pytest --cov=alfresco_mcp_server --cov-report=term-missing

# Run specific test categories
pytest -m "unit"           # Unit tests only
pytest -m "fastmcp"        # FastMCP 2.0 tests
pytest -m "integration"    # Integration tests (requires Alfresco)

🧪 See Testing Guide for detailed testing strategies

🧪 Test Categories and Execution

The project includes 4 levels of testing:

1. 📋 Unit Tests (122 tests) - Fast, mocked, isolated component testing.
2. 🔗 Integration Tests (21 tests) - Live Alfresco server testing.
3. 📝 Comprehensive Tests - Automated core document lifecycle scenarios.
4. 📊 Coverage Tests - Cover edge cases and error paths.

🧪 Development

Setup Development Environment

git clone <repository>
cd python-alfresco-mcp-server

# UV handles everything automatically - no manual venv setup needed!
uv sync --extra dev        # Install with development tools
uv sync --extra test       # With testing tools
uv sync --extra all        # Everything

# Run immediately to test that installation worked
uv run python-alfresco-mcp-server --help

# Install python-alfresco-api for local development (if needed)
uv add --editable ../python-alfresco-api

Traditional Development Setup: See the Installation with pip and pipx for pip - based development setup.

💡 Examples

Real - world implementation patterns from beginner to enterprise:

• 💡 Examples Library - Complete navigation and learning paths.
• 🏃 Quick Start - 5 - minute introduction and basic operations.
• 📋 Document Lifecycle - Complete process demonstration.
• 🚀 Transport Examples - STDIO, HTTP, and SSE protocols.
• ⚡ Batch Operations - High - performance bulk processing.
• 🛡️ Error Handling - Resilience patterns.
• 📊 Examples Summary - Overview and statistics.

🤝 Contributing

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/new-feature).
3. Commit your changes (git commit -m 'Add new feature').
4. Push to the branch (git push origin feature/new-feature).
5. Open a Pull Request.

📄 License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

🔗 Related Projects and References

• Hyland Alfresco - Content management platform (Enterprise and Community editions).
• python-alfresco-api - The underlying Alfresco API library.
• FastMCP 2.0 - Modern framework for building MCP servers.
• FastMCP Documentation - Complete FastMCP framework documentation and guides.
• Model Context Protocol - Official MCP specification and documentation.
• Playbooks.com MCP List - Python Alfresco MCP Server listing.
• PulseMCP.com MCP List - Python Alfresco MCP Server listing.
• Glama.ai MCP List - Glama Alfresco list including Python Alfresco MCP Server listing.
• MCPMarket.com MCP List - Python Alfresco MCP Server listing.

🙋‍♂️ Support

• 📚 Documentation: Complete guides in .
• 💡 Examples: Implementation patterns in .
• 🧪 Testing: Quality assurance in .
• 🔍 MCP Inspector: Development testing in .
• 🛠️ Troubleshooting: Problem solving in .
• 🐛 Issues: GitHub Issues

🚀 MCP server built with python-alfresco-api and FastMCP 2.0