python-alfresco-mcp-server
Advanced tools
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
The fastest way to get started - install directly from PyPI:
# Option 1: pipx (Recommended) - installs in isolated environment + makes globally available
pipx install python-alfresco-mcp-server
# Option 2: pip - traditional package manager
pip install python-alfresco-mcp-server
# Option 3: UV (fastest) - Rust-based package manager
uv pip install python-alfresco-mcp-server
# Run immediately
python-alfresco-mcp-server --help
Why pipx? pipx automatically creates isolated environments for each tool while making commands globally available - eliminates dependency conflicts while providing system-wide access.
Note: You still need to configure your MCP client (Claude Desktop, MCP Inspector, etc.) with the appropriate configuration. See the MCP Client Setup section below for client configuration details.
For development or access to latest features:
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. Choose your installation method:
# Method 1: Official installer (recommended)
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Method 2: pip (if you prefer)
pip install uv
# Method 3: Package managers
# macOS with Homebrew
brew install uv
# Windows with Chocolatey
choco install uv
# Verify installation
uv --version
# Clone the repository
git clone https://github.com/stevereiner/python-alfresco-mcp-server.git
cd python-alfresco-mcp-server
Option A: UV (Recommended - Automatic everything + much faster):
# UV handles venv creation and dependency installation automatically
# Rust-based performance makes this much faster than pip
uv run python-alfresco-mcp-server --help
# Or install dependencies explicitly:
uv sync # Basic dependencies
uv sync --extra dev # With development tools
uv sync --extra test # With testing tools
uv sync --extra all # Everything
Option B: Traditional pip (Manual venv management):
# Create and activate virtual environment
python -m venv venv # Traditional Python creates 'venv'
source venv/bin/activate # Linux/macOS
# venv\Scripts\activate # Windows
# Note: UV creates '.venv' by default (not 'venv')
# Install MCP server
pip install -e .
# Or with development dependencies
pip install -e .[dev]
# Or with testing dependencies
pip install -e .[test]
# Or install everything
pip install -e .[all]
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
cp 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
Start Alfresco with Docker Compose
cd acs-deployment/docker-compose
Note: you will likely need to comment out activemq ports other than 8161 in community-compose.yaml
ports:
- "8161:8161" # Web Console
#- "5672:5672" # AMQP
#- "61616:61616" # OpenWire
#- "61613:61613" # STOMP
docker-compose -f community-compose.yaml up
With UV (Recommended - Automatic venv and dependency management):
# Run MCP server with STDIO transport (default)
uv run python-alfresco-mcp-server
# HTTP transport for web services
uv run python-alfresco-mcp-server --transport http --host 127.0.0.1 --port 8001
# SSE transport for real-time streaming
uv run python-alfresco-mcp-server --transport sse --host 127.0.0.1 --port 8003
Traditional Python (after manual venv setup):
# Run MCP server with STDIO transport (default)
python-alfresco-mcp-server
# Or directly with module (also STDIO by default)
python -m alfresco_mcp_server.fastmcp_server
# HTTP transport for web services
python -m alfresco_mcp_server.fastmcp_server --transport http --host 127.0.0.1 --port 8001
# SSE transport for real-time streaming
python -m alfresco_mcp_server.fastmcp_server --transport sse --host 127.0.0.1 --port 8003
Claude Desktop is the primary tested and recommended MCP client with native support for the Python Alfresco MCP Server.
📖 Complete Setup Guide: Claude Desktop Setup Guide
Quick Start:
For Users (PyPI Installation):
pipx install python-alfresco-mcp-serverclaude-desktop-config-user-windows.json or claude-desktop-config-user-macos.jsonFor Developers (Source Installation):
claude-desktop-config-developer-windows.json or claude-desktop-config-developer-macos.jsonUsing the Tools:
search_content (full text search)advanced_search (AFTS query language)search_by_metadata (property-based queries)cmis_search (CMIS SQL queries)Search and Analyze Prompt:
Repository Info Resource (and Tool):
Testing & Examples:
prompts-for-claude.md for 14 manual test scenarios and examplesFor Cursor, Claude Code, and other MCP clients:
📖 Complete Setup Guide: Client Configuration Guide
Quick Reference:
📖 Setup Guide: Complete MCP Inspector setup and connection instructions in MCP Inspector Setup Guide
Working Method (Recommended):
# With UV (recommended)
uv run python-alfresco-mcp-server --transport http --port 8003
# Or traditional method
python -m alfresco_mcp_server.fastmcp_server --transport http --port 8003
npx @modelcontextprotocol/inspector --config mcp-inspector-http-config.json --server python-alfresco-mcp-server
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<token>This approach avoids proxy connection errors and provides direct authentication.
💡 See Examples Library for usage patterns
| 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:
New Integration Tests:
prompts-for-claude.md now available as automated testsgit clone <repository>
cd python-alfresco-mcp-server
# Create virtual environment
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
# Install development dependencies
pip install -e .[dev]
# Install python-alfresco-api (local development)
pip install -e ../python-alfresco-api
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
FAQs
FastMCP 2.0 server for Alfresco Content Services integration
We found that python-alfresco-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Two npm packages masquerading as WhatsApp developer libraries include a kill switch that deletes all files if the phone number isn’t whitelisted.
Research
/Security News
Socket uncovered 11 malicious Go packages using obfuscated loaders to fetch and execute second-stage payloads via C2 domains.
Security News
TC39 advances 11 JavaScript proposals, with two moving to Stage 4, bringing better math, binary APIs, and more features one step closer to the ECMAScript spec.