YushengAuggie/phabricator-mcp-server
If you are the rightful owner of phabricator-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Phabricator MCP Server is a comprehensive Model Context Protocol server designed to facilitate intelligent interactions between AI assistants and Phabricator for enhanced task management and code review workflows.
Phabricator MCP Server
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact intelligently with Phabricator for advanced task management and code review workflows.
โจ Features
๐ Personal Authentication
- Per-User Authentication: Configure your personal Phabricator API token in your MCP client
- User Attribution: Comments and reviews appear under YOUR name instead of a shared service account
- Flexible Configuration: Supports both personal tokens and shared environment variables
- Standard MCP Integration: Follows MCP ecosystem best practices for authentication
๐ฏ Core Task Management
- Task Operations: View task details, read comments, add comments, subscribe users to tasks
- Rich Formatting: Well-structured output with task metadata, status, priority, and full comment threads
๐ Advanced Code Review
- Differential Management: View revisions, read comments, approve/reject code changes
- Intelligent Review Feedback: Analyze comments with surrounding code context for actionable insights
- Inline Comments: Add targeted feedback to specific lines in code reviews
- Code Context Analysis: Correlate review comments with actual code changes and locations
๐ Server Architecture
- HTTP/SSE Transport: FastMCP-based server for reliable production use (default on port 8932)
- stdio Transport: Legacy support for direct MCP client integration
- Comprehensive API: 11 specialized tools for complete Phabricator workflow automation
๐ง Smart Review Analysis
- Comment-Code Correlation: Intelligently link review feedback to specific code locations
- Contextual Code Display: Show surrounding code lines for better understanding
- Action Item Generation: Categorize feedback into actionable to-do items
- Priority Classification: Organize comments by Issues โ Suggestions โ Nits โ Other
๐ Available Tools
Task Management (3 tools)
get-task
- Get comprehensive task details with commentsadd-task-comment
- Add comments to taskssubscribe-to-task
- Subscribe users to task notifications
Code Review (8 tools)
get-differential
- Get basic differential revision detailsget-differential-detailed
- Get comprehensive review with code changesget-review-feedback
- : Get intelligent review analysis with code contextadd-differential-comment
- Add general comments to reviewsadd-inline-comment
- : Add targeted inline comments to specific code linesaccept-differential
- Accept/approve differential revisionsrequest-changes-differential
- Request changes with optional feedbacksubscribe-to-differential
- Subscribe users to review notifications
๐ Prerequisites
- Python 3.8+
- Phabricator instance with API access
- API token from Phabricator (Settings โ Conduit API Tokens)
โก Quick Start
Automated Setup (Recommended)
# Clone and navigate
git clone https://github.com/YushengAuggie/phabricator-mcp-server.git
cd phabricator-mcp-server
# Configure credentials
echo "PHABRICATOR_TOKEN=your-32-character-api-token" > .env
echo "PHABRICATOR_URL=https://your-phabricator-instance.com/api/" >> .env
# Start server (handles all setup automatically)
python3 start.py --mode http
The server starts on http://localhost:8932
with automatic dependency management.
Manual Setup
# Create virtual environment
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install with dependencies
pip install -e .
# Start HTTP server
python src/servers/http_server.py
# Or start stdio server
python src/servers/stdio_server.py
โ๏ธ Configuration
Authentication Configuration
The server supports hybrid authentication with two modes that work seamlessly together:
- Personal API Token (Recommended): Pass your personal token through MCP client configuration for user attribution
- Environment Variable Fallback: Use a shared service account token via environment variables
๐ Getting Your API Token:
- Go to your Phabricator instance โ Settings โ API Tokens
- Create a new token with appropriate permissions
- Copy the 32-character token for use in configuration
๐ Finding Your Phabricator URL:
Your Phabricator API URL should end with /api/
and typically looks like:
https://phabricator.example.com/api/
https://phab.yourcompany.com/api/
https://your-domain.phabricator.com/api/
If unsure, check your Phabricator instance's main page - the URL is usually [your-base-url]/api/
๐ MCP Client Configuration
HTTP/SSE Transport (Recommended)
The server automatically detects your environment configuration:
Claude Code CLI (Easiest):
claude mcp add --transport sse phabricator http://localhost:8932/sse \
--env "PHABRICATOR_TOKEN=api-xxxxxxx" \
--env "PHABRICATOR_URL=https://example.com/api/"
Replace
api-xxxxxxx
with your actual API token andhttps://example.com/api/
with your Phabricator instance URL
Manual Configuration:
{
"mcpServers": {
"phabricator": {
"url": "http://localhost:8932/sse",
"env": {
"PHABRICATOR_TOKEN": "api-xxxxxxx",
"PHABRICATOR_URL": "https://example.com/api/"
}
}
}
}
stdio Transport
For Claude Desktop and direct MCP integration:
{
"mcpServers": {
"phabricator": {
"command": "python",
"args": ["path/to/phabricator-mcp-server/start.py"],
"cwd": "path/to/phabricator-mcp-server",
"env": {
"PHABRICATOR_TOKEN": "api-xxxxxxx",
"PHABRICATOR_URL": "https://example.com/api/"
}
}
}
}
Multiple Authentication Options
The server supports multiple ways to authenticate:
- Personal Token in Tools: Some tools accept an
api_token
parameter - Environment Variables: Set
PHABRICATOR_TOKEN
in MCP client config - Fallback Token: Create
.env
file in server directory
Priority Order: Personal token โ MCP environment โ Server .env
file
Server Environment Variables (Fallback)
Create .env
file in project root for fallback authentication:
# Fallback: Shared service account token
PHABRICATOR_TOKEN=your-shared-token-here
# Optional: Custom Phabricator URL (auto-detected from token by default)
# PHABRICATOR_URL=https://your-phabricator-instance.com/api/
# Optional: Custom server port (default: 8932)
# MCP_SERVER_PORT=8932
๐ง Advanced Configuration
User Attribution
- Personal tokens: Comments appear under YOUR name
- Shared tokens: Comments appear under the service account name
- Mixed usage: Different tools can use different tokens
Token Security
- Tokens are passed securely through MCP protocol
- No tokens stored on disk (except optional
.env
fallback) - Each client can use their own personal token
Troubleshooting Authentication
If you see authentication errors:
- Check token validity: Test your token directly with Phabricator API
- Verify configuration: Ensure
PHABRICATOR_TOKEN
is set correctly - Check environment: Run server with debugging to see environment variables
- Use personal token: Pass
api_token
parameter directly to tools
Debugging Commands:
# Check if server can start with your token
PHABRICATOR_TOKEN=your-token python start.py --mode http
# Test token manually
curl -d "api.token=your-token" https://your-phabricator-instance.com/api/user.whoami
๐ป Usage
With Claude Desktop
Add to Claude Desktop configuration (claude_desktop_config.json
):
{
"mcpServers": {
"phabricator": {
"command": "python",
"args": ["path/to/phabricator-mcp-server/start.py", "--mode", "stdio"],
"cwd": "path/to/phabricator-mcp-server"
}
}
}
With HTTP/SSE Transport
{
"mcpServers": {
"phabricator": {
"url": "http://localhost:8932/sse"
}
}
}
Programmatic Usage
from src.core.client import PhabricatorClient
# Initialize client
client = PhabricatorClient(
token="your-32-char-api-token",
host="https://your-instance.com/api/"
)
# Get enhanced review feedback with code context
feedback = await client.get_review_feedback_with_code_context("12345", context_lines=7)
# Add inline comment to specific line
await client.add_inline_comment("12345", "src/file.py", 42, "Consider using a more descriptive variable name")
# Get task with full context
task = await client.get_task("6789")
comments = await client.get_task_comments("6789")
Example: AI-Powered Code Review
# Get intelligent review feedback
feedback_data = await client.get_review_feedback_with_code_context("D123", context_lines=5)
# The feedback includes:
# - Comments correlated with specific code locations
# - Surrounding code context for each comment
# - Action items categorized by priority
# - File-by-file breakdown of changes
๐งช Development & Testing
Install Development Dependencies
# Install with dev dependencies
pip install -e ".[dev]"
# Or with uv (faster)
uv pip install -e ".[dev]"
Run Tests
# Run all tests with our test runner
python run_tests.py
# Run specific test suites
python -m pytest src/tests/test_tool_completeness.py -v
python -m pytest src/tests/test_tool_integration.py -v
# Run with coverage
python -m pytest --cov=src --cov-report=html
Code Quality
# Format code
black src/
ruff check src/ --fix
# Type checking
mypy src/
# Run all quality checks
black src/ && ruff check src/ && mypy src/ && python run_tests.py
Testing Features
- Tool Completeness: Validates all 11 tools are properly configured
- Integration Testing: Tests all tools with realistic mock data
- Error Handling: Validates graceful failure modes
- Argument Validation: Ensures correct required/optional parameters
- Mock Phabricator: No API calls needed for testing
๐ฏ Advanced Features
Intelligent Review Feedback Analysis
The get-review-feedback
tool provides advanced analysis:
# Returns structured feedback with:
{
"revision": {...}, # Revision metadata
"review_feedback": [ # Enhanced comment analysis
{
"comment": "Fix this issue",
"author": "reviewer-phid",
"type": "inline",
"code_context": {
"file": "src/example.py",
"target_line": 42,
"hunk_info": "@@ -40,7 +40,7 @@",
"lines": [ # Surrounding code context
{"line_number": 40, "content": "def example():", "is_target": False},
{"line_number": 41, "content": " # TODO: fix this", "is_target": False},
{"line_number": 42, "content": " return broken_code", "is_target": True},
{"line_number": 43, "content": " # end function", "is_target": False},
]
},
"primary_file": "src/example.py",
"primary_line": 42
}
],
"summary": "Analysis summary with actionable insights",
"total_comments": 5,
"comments_with_context": 3
}
Smart Comment-Code Correlation
- Keyword Extraction: Identifies variable names, function names in comments
- Code Location Mapping: Links comments to specific files and line numbers
- Context Enrichment: Shows surrounding code for better understanding
- Priority Classification: Organizes feedback by importance
๐ค Contributing
We welcome contributions! Here's how to get started:
# Fork and clone the repository
git clone https://github.com/your-username/phabricator-mcp-server.git
cd phabricator-mcp-server
# Create feature branch
git checkout -b feature/amazing-feature
# Make changes and test
python run_tests.py
# Commit and push
git commit -m 'feat: add amazing feature'
git push origin feature/amazing-feature
# Open a Pull Request
Development Guidelines
- Follow existing code style (black + ruff)
- Add tests for new features
- Update documentation as needed
- Ensure all quality checks pass
๐ License
MIT License - see file for details.
๐ Links
- Repository: https://github.com/YushengAuggie/phabricator-mcp-server
- Model Context Protocol: https://modelcontextprotocol.io/
- FastMCP: https://github.com/jlowin/fastmcp
- Phabricator API: https://secure.phabricator.com/book/phabricator/article/conduit/