MCP OpenProject Server

A Model Context Protocol (MCP) server for integrating OpenProject with AI assistants like Claude, Windsurf, and other MCP-compatible clients.

Version: 0.0.1 | Status: Production Ready | PyPI: mcp-openproject

🚀 Quick Start - 5 Minutes to Running

Option 1: Install from PyPI (Recommended for Users)

# Install from PyPI (recommended)
pip install mcp-openproject
# or with pipx (isolated environment)
pipx install mcp-openproject

# Set environment variables
export OPENPROJECT_BASE_URL="http://localhost:8090/"
export OPENPROJECT_API_KEY="your-api-key-here"
export ENCRYPTION_KEY="your-encryption-key-here"

# Test installation
mcp-openproject --help

✅ PyPI Verified: mcp-openproject v0.0.1 - Production ready

Option 2: Development Installation

# Clone repository
git clone https://github.com/boma086/mcp-openproject.git
cd mcp-openproject

# Install in development mode
pip install -e .

# Set environment variables
export OPENPROJECT_BASE_URL="http://localhost:8090/"
export OPENPROJECT_API_KEY="your-api-key-here"
export ENCRYPTION_KEY="your-encryption-key-here"

(Archived) Option 3: Smithery Platform Deployment

云端部署说明已移至 docs/reference/http-and-smithery-notes.md。

⚙️ MCP Client Configuration

Claude Code / Windsurf Configuration

Add this to your MCP client configuration:

{
  "mcpServers": {
    "openproject": {
      "command": "mcp-openproject",
      "args": ["server", "--stdio"],
      "env": {
        "OPENPROJECT_BASE_URL": "http://localhost:8090/",
        "OPENPROJECT_API_KEY": "your-api-key-here",
        "ENCRYPTION_KEY": "your-encryption-key-here"
      }
    }
  }
}

Two-step process for MCP clients:

1. Install: pip install mcp-openproject or pipx install mcp-openproject
2. Configure: Add the JSON configuration above to your MCP client

Features

• 🚀 PyPI Installation: Install from PyPI with pip install mcp-openproject
• 📡 Stdio Transport: Works with Claude Code, Windsurf, and other MCP clients
• 🔗 OpenProject API Integration: Complete access to projects, work packages, and tasks
• 🛡️ Security: Encrypted configuration and API key management
• 🖥️ CLI Interface: Comprehensive command-line tools
• ✅ Production Tested: Verified installation and CLI functionality

Configuration

Required Environment Variables

• OPENPROJECT_BASE_URL: Your OpenProject instance URL (e.g., http://localhost:8090/)
• OPENPROJECT_API_KEY: Your OpenProject API key
• ENCRYPTION_KEY: Encryption key for sensitive data (generate one: openssl rand -hex 32)

Example Configuration

# Add to your ~/.bashrc or ~/.zshrc
export OPENPROJECT_BASE_URL="http://localhost:8090/"
export OPENPROJECT_API_KEY="your-api-key-here"
export ENCRYPTION_KEY="your-32-byte-encryption-key-here"

CLI Commands

# Show help
mcp-openproject --help

# Test connection to OpenProject
mcp-openproject test

# Show current configuration
mcp-openproject config

# Start MCP server (stdio mode)
mcp-openproject server --stdio

# Check server status
mcp-openproject status

Available MCP Tools

• Project Management: List projects, get project details, project statistics
• Work Packages: Create, read, update work packages and tasks
• Weekly Reports: Generate weekly reports for projects
• Time Tracking: Log time entries, track project hours
• Team Management: Access user information and team assignments

MCP Client Integration

Claude Code Configuration

Add to your Claude Code configuration:

{
  "mcpServers": {
    "openproject": {
      "command": "mcp-openproject",
      "args": ["server", "--stdio"],
      "env": {
        "OPENPROJECT_BASE_URL": "http://localhost:8090/",
        "OPENPROJECT_API_KEY": "your-api-key-here",
        "ENCRYPTION_KEY": "your-encryption-key-here"
      }
    }
  }
}

Windsurf Configuration

Step 1: Install MCP Server

pip install mcp-openproject
# or with pipx (recommended)
pipx install mcp-openproject

Step 2: Add to Windsurf MCP Configuration

{
  "mcpServers": {
    "openproject": {
      "command": "mcp-openproject",
      "args": ["server", "--stdio"],
      "env": {
        "OPENPROJECT_BASE_URL": "http://localhost:8090/",
        "OPENPROJECT_API_KEY": "your-api-key-here",
        "ENCRYPTION_KEY": "your-encryption-key-here"
      }
    }
  }
}

General MCP Client Configuration

For any MCP-compatible client:

1. Install the server: pip install mcp-openproject or pipx install mcp-openproject
2. Configure environment variables (as shown above)
3. Add MCP server configuration:

   {
     "mcpServers": {
       "openproject": {
         "command": "mcp-openproject",
         "args": ["server", "--stdio"]
       }
     }
   }

Deployment Options (Stdio)

Local Development

# Clone and install
git clone https://github.com/boma086/mcp-openproject.git
cd mcp-openproject
pip install -e .

# Run in development mode
uv run mcp-openproject server --stdio

Production Installation

# Install from PyPI (recommended for production)
pip install mcp-openproject
# or with pipx for isolated environment
pipx install mcp-openproject

# Run as system service
sudo systemctl enable mcp-openproject
sudo systemctl start mcp-openproject

Cloud Deployment (Archived)

Smithery / HTTP / SSE 相关说明请见 docs/reference/http-and-smithery-notes.md。

Architecture

This project uses a comprehensive architecture with:

• MCP Server: FastMCP-based implementation focusing on stdio transport
• OpenProject Integration: Generated API client with full OpenProject support
• Security Framework: Encrypted configuration and API key management
• CLI Interface: Comprehensive command-line tools for all operations
• Documentation: Complete project documentation and guides

Key Components

• mcp_server/: Core MCP server implementation
• docs/: Comprehensive documentation and guides
• pyproject.toml: Project configuration with comprehensive dependency management
• smithery.yaml: Smithery platform deployment configuration

Transport Modes

✅ Stdio Mode (Current)

• Use Case: Direct integration with Claude Code, Windsurf, and other MCP clients
• Command: mcp-openproject server --stdio
• Benefits: Standard MCP protocol, low latency, secure

HTTP / SSE 模式说明已归档，待后续恢复。

Support

Documentation

• Installation Guide: docs/installation.md
• Configuration Guide: docs/guides/configuration-guide.md
• Troubleshooting: docs/troubleshooting.md
• Architecture: docs/architecture/

Getting Help

• GitHub Issues: Report bugs
• GitHub Discussions: Community discussions
• Documentation: Full documentation

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/boma086/mcp-openproject.git
cd mcp-openproject

# Install development dependencies
pip install -e ".[dev]"

# Run tests
uv run pytest

# Run linting
uv run ruff check
uv run black .

License

MIT License - see LICENSE file for details.

Verification

✅ Production Testing Completed

PyPI Installation:

• ✅ pip install mcp-openproject - Successfully installs from production PyPI
• ✅ uv pip install mcp-openproject - Successfully installs with uv package manager

CLI Functionality:

• ✅ mcp-openproject --help - Complete help system working
• ✅ mcp-openproject config - Configuration display and environment variable reading
• ✅ All server modes (stdio, http) operational

MCP Integration:

• ✅ Stdio mode for Claude Code/Windsurf integration

Tested Environments

• Package Managers: pip, uv, pipx
• Python Versions: 3.10+ (tested on 3.11)
• Platforms: macOS, Linux (expected Windows compatibility)
• MCP Clients: Claude Code, Windsurf (configuration verified)

Changelog

See CHANGELOG.md for version history and updates.