Python Alfresco MCP Server v1.1 🚀

Model Context Protocol Server for Alfresco Content Services

A full featured MCP server for Alfresco in search and content management areas. It provides the following tools: full text search (content and properties), advanced search, metadata search, CMIS SQL like search, upload, download, checkin, checkout, cancel checkout, create folder, folder browse, delete node, and get/set properties. Also has a tool for getting repository status/config (also a resource). Has one prompt example. Built with FastMCP 2.0. Features complete documentation, examples, and config for various MCP clients (Claude Desktop, MCP Inspector, references to configuring others).

🌟 What's New in v1.1

Modular Architecture & Enhanced Testing

FastMCP: v1.0 had FastMCP 2.0 implementation that had all tools implementations in the fastmcp_server.py file
Code Modularization in v1.1: Split monolithic single file into organized modular structure with separate files
Directory Organization: Organized into tools/search/, tools/core/, resources/, prompts/, utils/ directories
Enhanced Testing: Complete test suite transformation - 143 tests with 100% pass rate
Client Configuration Files: Added dedicated Claude Desktop and MCP Inspector configuration files
Live Integration Testing: 21 Alfresco server validation tests for real-world functionality
Python-Alfresco-API: python-alfresco-mcp-server v1.1 requires the v1.1.1 python-alfresco-api package

📚 Complete Documentation

Documentation & Examples

📚 Complete Documentation: 10 guides covering setup to deployment
💡 Examples: 6 practical examples from quick start to implementation patterns
🔧 Configuration Management: Environment variables, .env files, and command-line configuration
**🏗️ Setup instruction for use with MCP client

Learning Resources

🚀 Quick Start Guide: 5-minute setup and first operations
🤖 Claude Desktop Setup: Complete Claude Desktop configuration for users and developers
🔧 Client Configurations: Setup guide for Cursor, Claude Code, and other MCP clients
📖 Examples Library: Implementation patterns and examples

📖 Guides covering setup, deployment, and usage:

📚 Documentation Hub - Complete navigation and overview
🚀 Quick Start Guide - 5-minute setup and first operations
📦 Installation with pip and pipx - Traditional Python package installation methods
🤖 Claude Desktop Setup - Complete Claude Desktop configuration for users and developers
🔧 Client Configurations - Setup guide for Cursor, Claude Code, and other MCP clients
🔍 MCP Inspector Setup - Development and testing with MCP Inspector
🔍 API Reference - Complete tool and resource documentation
⚙️ Configuration Guide - Development to deployment
🧪 Testing Guide - Quality assurance and test development
🛠️ Troubleshooting Guide - Problem diagnosis and resolution

🚀 Features

Content Management and Search Tools

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

MCP Architecture

FastMCP 2.0 Framework: Modern, high-performance MCP server implementation
Multiple Transports:
- STDIO (direct MCP protocol) - Default and fastest
- HTTP (RESTful API) - Web services and testing
- SSE (Server-Sent Events) - Real-time streaming updates
Enterprise Security: OAuth 2.1 (optional)
Type Safety: Full Pydantic v2 models
In-Memory Testing: Client testing with faster execution
Configuration: Environment variables, .env files

Alfresco Integration

Works with Alfresco Community (tested) and Enterprise editions

📋 Requirements

Python 3.10+
Alfresco Content Services (Community or Enterprise)

Note: The python-alfresco-api >= 1.1.1 dependency is automatically installed with python-alfresco-mcp-server

🛠️ Installation

Install Python

You need to have Python 3.10+ installed for the sections below. If not, 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 both uv (package manager) and uvx (tool runner). 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. 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!

Why UVX? UVX combines the benefits of pipx (isolated environments + global availability) with UV's Rust-based speed and modern dependency resolution. It automatically installs packages on first use.

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

UV is a modern Python package manager written in Rust that handles everything automatically. Much faster than pip due to its compiled nature and optimized dependency resolution.

# 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.

Note: You still need to configure your MCP client (Claude Desktop, MCP Inspector, etc.) with the appropriate configuration. See the MCP Client Setup and Use section below for client configuration details.

Source Installation (For Development)

For development or access to latest features:

# 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

4. 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

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

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

Python-Alfresco-MCP-Server was tested with Claude Desktop which is recommended as an end user MCP client. Python-Alfresco-MCP-Server was also tested with MCP Inspector which is recommended for developers to test tools with argument values.

🤖 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:

The Claude Desktop configuration differs based on how you installed the MCP server:

1. UVX (Recommended - Modern tool runner):

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

Sample Config Files:
- Windows: claude-desktop-config-uvx-windows.json
- macOS: claude-desktop-config-uvx-macos.json
UVX automatically handles isolation and global availability
Fastest and most modern approach

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: claude-desktop-config-uv-windows.json
- macOS: claude-desktop-config-uv-macos.json
Uses uv run with cwd pointing to your project directory
UV automatically finds and uses the .venv from the project directory
Works for both source installations and after uv tool install

3. Traditional Methods (pipx/pip):

For traditional installation methods, see the Installation with pip and pipx which covers:

pipx: claude-desktop-config-pipx-windows.json / claude-desktop-config-pipx-macos.json
pip: Manual venv path configuration

🔐 Tool-by-Tool Permission System: Claude Desktop will prompt you individually for each tool on first use. Since this MCP server has 15 tools, you may see up to 15 permission prompts if you use all features. For each tool, you can choose:

"Allow once" - Approve this single tool use only
"Always allow" - Approve all future uses of this specific tool automatically (recommended for regular use)

This tool-by-tool security feature ensures you maintain granular control over which external tools can be executed.

🛡️ Virus Scanner Note: If you have virus checkers like Norton 360, don't worry if you get a "checking" message once for pip, pipx, uv, uvx, or python-alfresco-mcp-server.exe - this is normal security scanning behavior.

Using the Tools:

Chat naturally about what you want to do with documents and search
Mention "Alfresco" to ensure the MCP server is used (e.g., "In Alfresco...")
Use tool-related keywords - mention something close to the tool name
Follow-up prompts will know the document from previous context

Example 1: Document Management

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'"
Update properties: "Set the description property of this document to 'my desc'"
Check out the document
Cancel checkout
Check out again
Check in as a major version
Download the document
Upload a second document from "C:\1 sample files\cmispress.pdf"

Note: Claude will figure out to use base64 encoding for the first upload on a second try

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 Search and tools button (two horizontal lines with circles icon) in the chat box and choose "python-alfresco-mcp-server" - this allows you 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 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 prompts-for-claude.md 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)
Purpose: Web-based tool for testing MCP servers and individual tools with custom parameters

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>
This step applies to all installation methods (uv, uvx, pip, pipx)

This approach avoids proxy connection errors and provides direct authentication.

🔧 Other MCP Clients

For Cursor, Claude Code, and other MCP clients:

📖 Complete Setup Guide: Client Configuration Guide

🛠️ Available Tools (15 Total)

🔍 Search Tools (4)

Tool	Description	Parameters
`search_content`	Search documents and folders	`query` (str), `max_results` (int), `node_type` (str)
`advanced_search`	Advanced search with filters	`query` (str), `content_type` (str), `created_after` (str), etc.
`search_by_metadata`	Search by metadata properties	`property_name` (str), `property_value` (str), `comparison` (str)
`cmis_search`	CMIS SQL queries	`cmis_query` (str), `preset` (str), `max_results` (int)

🛠️ Core Tools (11)

Tool	Description	Parameters
`browse_repository`	Browse repository folders	`node_id` (str)
`repository_info`	Get repository information	None
`upload_document`	Upload new document	`filename` (str), `content_base64` (str), `parent_id` (str), `description` (str)
`download_document`	Download document content	`node_id` (str), `save_to_disk` (bool)
`create_folder`	Create new folder	`folder_name` (str), `parent_id` (str), `description` (str)
`get_node_properties`	Get node metadata	`node_id` (str)
`update_node_properties`	Update node metadata	`node_id` (str), `name` (str), `title` (str), `description` (str), `author` (str)
`delete_node`	Delete document/folder	`node_id` (str), `permanent` (bool)
`checkout_document`	Check out for editing	`node_id` (str), `download_for_editing` (bool)
`checkin_document`	Check in after editing	`node_id` (str), `comment` (str), `major_version` (bool), `file_path` (str)
`cancel_checkout`	Cancel checkout/unlock	`node_id` (str)

📖 See API Reference for detailed tool documentation

📊 Available Resources

Repository Information

Resource	Description	Access Method
`repository_info`	Get comprehensive repository information including version, edition, license details, installed modules, and system status	Available as both MCP resource and tool

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

Prompt	Description	Parameters
`search_and_analyze`	Interactive form for guided content search and analysis	`query` (search terms), `analysis_type` (summary/detailed/trends/compliance)

The Search and Analyze Prompt provides:

Interactive Form: User-friendly interface with 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

Environment Variable	Default	Description
`ALFRESCO_URL`	`http://localhost:8080`	Alfresco server URL
`ALFRESCO_USERNAME`	`admin`	Username for authentication
`ALFRESCO_PASSWORD`	`admin`	Password for authentication
`ALFRESCO_VERIFY_SSL`	`false`	Verify SSL certificates
`ALFRESCO_TIMEOUT`	`30`	Request timeout (seconds)
`FASTAPI_HOST`	`localhost`	FastAPI host
`FASTAPI_PORT`	`8000`	FastAPI port
`LOG_LEVEL`	`INFO`	Logging level
`MAX_FILE_SIZE`	`100000000`	Max upload size (bytes)

⚙️ 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 - Coverage of all functionality
122 Unit Tests: 100% passed - Core functionality validated with mocking (FastMCP 2.0, tools, coverage)
21 Integration Tests: 100% passed - Live server testing (search, upload, download, document lifecycle)
Integration Tests: Automated end-to-end testing covering all core document lifecycle scenarios
Performance Validated: Search <1s, concurrent operations, 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
Overall Project: 51% coverage of comprehensive codebase

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:

📋 Unit Tests (122 tests) - Fast, mocked, isolated component testing
🔗 Integration Tests (21 tests) - Live Alfresco server testing
📝 Comprehensive Tests - Automated core document lifecycle scenarios
📊 Coverage Tests - Edge cases and error path coverage

🧪 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

Fork the repository
Create a feature branch (git checkout -b feature/new-feature)
Commit your changes (git commit -m 'Add new feature')
Push to the branch (git push origin feature/new-feature)
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 ./docs/
💡 Examples: Implementation patterns in ./examples/
🧪 Testing: Quality assurance in ./docs/testing_guide.md
🔍 MCP Inspector: Development testing in ./docs/mcp_inspector_setup.md
🛠️ Troubleshooting: Problem solving in ./docs/troubleshooting.md
🐛 Issues: GitHub Issues

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

Alfresco MCP Server

README Documentation