Skip to main content
Glama

Alfresco MCP Server

by stevereiner

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

📖 Guides covering setup, deployment, and usage:

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

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.

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"] }

2. UV (Development or source installations):

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

3. Traditional Methods (pipx/pip):

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

🔐 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

  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"

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

🔍 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)

ToolDescriptionParameters
search_contentSearch documents and foldersquery (str), max_results (int), node_type (str)
advanced_searchAdvanced search with filtersquery (str), content_type (str), created_after (str), etc.
search_by_metadataSearch by metadata propertiesproperty_name (str), property_value (str), comparison (str)
cmis_searchCMIS SQL queriescmis_query (str), preset (str), max_results (int)

🛠️ Core Tools (11)

ToolDescriptionParameters
browse_repositoryBrowse repository foldersnode_id (str)
repository_infoGet repository informationNone
upload_documentUpload new documentfilename (str), content_base64 (str), parent_id (str), description (str)
download_documentDownload document contentnode_id (str), save_to_disk (bool)
create_folderCreate new folderfolder_name (str), parent_id (str), description (str)
get_node_propertiesGet node metadatanode_id (str)
update_node_propertiesUpdate node metadatanode_id (str), name (str), title (str), description (str), author (str)
delete_nodeDelete document/foldernode_id (str), permanent (bool)
checkout_documentCheck out for editingnode_id (str), download_for_editing (bool)
checkin_documentCheck in after editingnode_id (str), comment (str), major_version (bool), file_path (str)
cancel_checkoutCancel checkout/unlocknode_id (str)

📖 See API Reference for detailed tool documentation

📊 Available Resources

Repository Information

ResourceDescriptionAccess Method
repository_infoGet comprehensive repository information including version, edition, license details, installed modules, and system statusAvailable 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

PromptDescriptionParameters
search_and_analyzeInteractive form for guided content search and analysisquery (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 VariableDefaultDescription
ALFRESCO_URLhttp://localhost:8080Alfresco server URL
ALFRESCO_USERNAMEadminUsername for authentication
ALFRESCO_PASSWORDadminPassword for authentication
ALFRESCO_VERIFY_SSLfalseVerify SSL certificates
ALFRESCO_TIMEOUT30Request timeout (seconds)
FASTAPI_HOSTlocalhostFastAPI host
FASTAPI_PORT8000FastAPI port
LOG_LEVELINFOLogging level
MAX_FILE_SIZE100000000Max 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:

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

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

🙋‍♂️ Support


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

-
security - not tested
A
license - permissive license
-
quality - not tested

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Python-based server that provides AI-native access to Alfresco content management operations through the Model Context Protocol, enabling search, document lifecycle management, version control, and other content operations.

  1. 🌟 What's New in v1.1
    1. Modular Architecture & Enhanced Testing
  2. 📚 Complete Documentation
    1. Documentation & Examples
    2. Learning Resources
    3. 📖 Guides covering setup, deployment, and usage:
  3. 🚀 Features
    1. Content Management and Search Tools
    2. MCP Architecture
    3. Alfresco Integration
  4. 📋 Requirements
    1. 🛠️ Installation
      1. Install Python
      2. UV/UVX Setup (Recommended)
      3. Option A: UVX - Modern Tool Runner (Recommended for Users)
      4. Option B: UV - Modern Package Manager (Recommended for Development)
      5. Option C: Traditional Methods (pip and pipx)
      6. Source Installation (For Development)
      7. 4. Configure Alfresco Connection
    2. Alfresco Installation
      1. 🚀 Usage
        1. MCP Server Startup
        2. MCP Client Setup and Use
      2. 🛠️ Available Tools (15 Total)
        1. 🔍 Search Tools (4)
        2. 🛠️ Core Tools (11)
      3. 📊 Available Resources
        1. Repository Information
      4. 🎯 Available Prompts
        1. Search and Analyze Prompt
      5. 🔧 Configuration Options
        1. 🏗️ Architecture
          1. 🧪 Testing & Quality
            1. Test Suite Overview
            2. Coverage Report (Post-Cleanup)
            3. Run Tests
            4. 🧪 Test Categories and Execution
          2. 🧪 Development
            1. Setup Development Environment
          3. 💡 Examples
            1. Real-world implementation patterns from beginner to enterprise:
          4. 🤝 Contributing
            1. 📄 License
              1. 🔗 Related Projects and References
                1. 🙋‍♂️ Support

                  Related MCP Servers

                  • -
                    security
                    A
                    license
                    -
                    quality
                    A Model Context Protocol server that enables seamless execution of commands, Python code, web content fetching, and reusable task management with secure credentials handling.
                    Last updated -
                    2
                    Python
                    MIT License
                    • Apple
                  • -
                    security
                    F
                    license
                    -
                    quality
                    A Model Context Protocol server that enables AI assistants like Claude to perform Python development tasks through file operations, code analysis, project management, and safe code execution.
                    Last updated -
                    5
                    Python
                    • Linux
                    • Apple
                  • A
                    security
                    A
                    license
                    A
                    quality
                    A Model Context Protocol server that enables AI assistants to interact with Confluence content, supporting operations like retrieving, searching, creating, and updating pages and spaces.
                    Last updated -
                    9
                    8
                    TypeScript
                    MIT License
                  • -
                    security
                    F
                    license
                    -
                    quality
                    A comprehensive Model Context Protocol server that provides over 50 file and system management tools for AI models, including navigation, file operations, search, compression, and system information capabilities.
                    Last updated -
                    Python

                  View all related MCP servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/stevereiner/python-alfresco-mcp-server'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server