Mentioned as a related project (Box MCP Server) for similar content management functionality
Provides an HTTP transport option for testing the MCP server, with API documentation available at /docs endpoint
Uses Pydantic v2 models for type safety in the server implementation
Built as a Python-based server for Alfresco Content Services, requiring Python 3.8+
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 withpython-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:
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.
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:
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.
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:
4. Configure Alfresco Connection
Option 1: Environment Variables
Option 2: .env file (recommended - cross-platform):
Note: The
.env
file is not checked into git for security. Usesample-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
Move to Docker Compose directory
Edit community-compose.yaml
- Note: you will likely need to comment out activemq ports other than 8161
Start Alfresco with Docker Compose
🚀 Usage
MCP Server Startup
With UVX (Recommended - Automatic isolation and global availability):
With UV (For development or source installations):
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):
- Sample Config Files:
- UVX automatically handles isolation and global availability
- Fastest and most modern approach
2. UV (Development or source installations):
- Sample Config Files:
- Uses
uv run
withcwd
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 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:
2. Start MCP Inspector with config:
UVX Installation (Recommended):
UV Installation (Development):
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
🧪 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
🧪 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
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
This server cannot be installed
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.
- 🌟 What's New in v1.1
- 📚 Complete Documentation
- 🚀 Features
- 📋 Requirements
- 🛠️ Installation
- Alfresco Installation
- 🚀 Usage
- 🛠️ Available Tools (15 Total)
- 📊 Available Resources
- 🎯 Available Prompts
- 🔧 Configuration Options
- 🏗️ Architecture
- 🧪 Testing & Quality
- 🧪 Development
- 💡 Examples
- 🤝 Contributing
- 📄 License
- 🔗 Related Projects and References
- 🙋♂️ Support
Related MCP Servers
- -securityAlicense-qualityA 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 -2PythonMIT License
- -securityFlicense-qualityA 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 -5Python
- AsecurityAlicenseAqualityA 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 -98TypeScriptMIT License
- -securityFlicense-qualityA 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