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

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"

Operation Tool Auth needed
Create a page from markdown create_wiki_page Username + password
Replace a page body / rename update_wiki_page Username + password
Read a page body as markdown get_wiki_page_content Username + password
Get page metadata get_wiki_page API key
List / add / delete attachments list_wiki_page_attachments, add_wiki_page_attachment, delete_attachment API key

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

Issue Solution
Server not appearing Check absolute path to index.ts, restart client
Authentication errors Verify API key is correct and has permissions
Connection timeout Check OPENPROJECT_URL is accessible
Bun command not found Ensure Bun is installed and in your PATH

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