Tonle OpenProject MCP Server

A Model Context Protocol (MCP) server that connects AI assistants (Claude, Cursor, Windsurf, etc.) to OpenProject's API v3.

Quick Start

1. Install Bun

curl -fsSL https://bun.sh/install | bash

2. Clone & Install

git clone https://github.com/liratanak/tonle.git
cd tonle
bun install

3. Configure Environment

Create a .env file or set environment variables:

OPENPROJECT_URL=https://your-instance.openproject.com
OPENPROJECT_API_KEY=your-api-key-here

Get your API key:

• Log into OpenProject → My Account → Access Tokens → Generate

4. Run the Server

# Stdio mode (default)
bun run index.ts

# HTTP mode
bun run start:http

5. Test with MCP Inspector

bunx @modelcontextprotocol/inspector bun run index.ts

Related MCP server: OpenProject MCP Server

Using with MCP Clients

Add to your MCP client configuration (e.g., claude_desktop_config.json, .cursor/mcp.json):

{
  "mcpServers": {
    "openproject": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/tonle/index.ts"],
      "env": {
        "OPENPROJECT_URL": "https://your-instance.openproject.com",
        "OPENPROJECT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Configuration file locations:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json

• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json

• Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json

• Cursor: .cursor/mcp.json in project root

What You Can Do

Once connected, you can ask your AI assistant to:

• "List all my OpenProject projects"

• "Create a new task in project X titled 'Setup testing environment'"

• "Show me all work packages assigned to me"

• "Update work package #123 to status 'In Progress'"

• "Move #45, #46 and #47 to the next sprint and assign them all to Bob" (bulk update in one call)

• "How many hours did Vanntha log last month?" (timesheet totals per user, project and day)

• "Summary total hours by members, by projects in 1 table for last month" (timesheet member × project summary table)

• "Show me wiki page 37 and attach these notes to it" (wiki page metadata + attachments — see the limitation below)

• And much more...

Wiki module support

Publish a markdown file straight to a project wiki:

"Use docs/KUP-Project-Specification.md to create a wiki page in the KUP project"

Why wiki writing needs a password. OpenProject's REST API cannot create or update wiki pages, and never returns page bodies — API v3 declares exactly one wiki endpoint, GET /api/v3/wiki_pages/{id}, whose response contains only id, title and links. (Docs claiming a POST /api/v3/projects/{id}/wiki_pages endpoint are wrong; it returns 404.) So the write tools log in and drive the same web forms the UI uses. Add to your environment:

OPENPROJECT_USERNAME=your-username
OPENPROJECT_PASSWORD=your-password

Use an account with the "edit wiki pages" permission, and note that accounts behind 2FA or SSO cannot be used. Without these variables everything else still works — only the three wiki write tools return an error explaining what to set.

Documentation

• ARCHITECTURE.md - Technical architecture, implementation details, and API reference

• MCP_SERVERS.md - Client-specific configuration examples (if available)

• LOGGING.md - Comprehensive logging system documentation

Features

• ✅ Complete OpenProject API v3 coverage (40+ endpoint categories)

• ✅ Work packages, projects, users, time entries, and more

• ✅ Stdio transport (local clients)

• ✅ HTTP transport (remote clients)

• ✅ Type-safe with TypeScript & Zod validation

• ✅ Comprehensive logging system (daily logs by caller/initiator)

Troubleshooting

Contributing

git clone https://github.com/liratanak/tonle.git
cd tonle
bun install
bun run dev    # Development mode
bun test       # Run tests

See ARCHITECTURE.md for detailed development information.

License

MIT License - See LICENSE file for details

Resources

• OpenProject: https://www.openproject.org/docs/

• OpenProject API: https://www.openproject.org/docs/api/

• MCP Specification: https://spec.modelcontextprotocol.io/

• MCP SDK: https://github.com/modelcontextprotocol/typescript-sdk