Alfresco
HTTP-SSEAI-native MCP server for Alfresco content management with comprehensive tools and documentation.
AI-native MCP server for Alfresco content management with comprehensive tools and documentation.
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).
tools/search/, tools/core/, resources/, prompts/, utils/ directoriesWorks with Alfresco Community (tested) and Enterprise editions
Note: The
python-alfresco-api >= 1.1.1dependency is automatically installed withpython-alfresco-mcp-server
You need to have Python 3.10+ installed for the sections below. If not, download the latest 3.13.x version from:
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
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.
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
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
.envfile is not checked into git for security. Usesample-dot-env.txtas a template.
📖 See Configuration Guide for complete setup options
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
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
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.
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.
📖 Complete Setup Guide: Claude Desktop Setup Guide
📥 Download Claude Desktop (Free and Pro versions):
🔧 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" }
uv run with cwd pointing to your project directory.venv from the project directoryuv tool install3. Traditional Methods (pipx/pip):
For traditional installation methods, see the Installation with pip and pipx which covers:
claude-desktop-config-pipx-windows.json / claude-desktop-config-pipx-macos.json🔐 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:
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:
Example 1: Document Management
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:"
More Examples: Create Folder, Browse Folders, Get Repository Info
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:
Repository Info Resource (and Tool):
Examples:
prompts-for-claude.md for examples testing the tools📖 Setup Guide: Complete MCP Inspector setup and connection instructions in MCP Inspector Setup Guide
📥 Install MCP Inspector:
npm install -g @modelcontextprotocol/inspectornpx @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:
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>This approach avoids proxy connection errors and provides direct authentication.
For Cursor, Claude Code, and other MCP clients:
📖 Complete Setup Guide: Client Configuration Guide
| 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) |
| 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
| 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:
📖 See API Reference for detailed resource documentation
| 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:
📖 See API Reference for detailed prompt documentation
| 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
┌─────────────────────────────────────────────────────┐
│ 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) │
└─────────────────────────────────────────────────────┘
# 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
The project includes 4 levels of testing:
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.
git checkout -b feature/new-feature)git commit -m 'Add new feature')git push origin feature/new-feature)This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
./docs/./examples/./docs/testing_guide.md./docs/mcp_inspector_setup.md./docs/troubleshooting.md🚀 MCP server built with python-alfresco-api and FastMCP 2.0