MCP-openproject

MCP Server for OpenProject with Netlify Express

View the deployed MCP function endpoint: https://gilded-fudge-69ca2e.netlify.app/mcp (Note: This endpoint is intended for MCP clients, not direct browser access).

About this MCP Server

This project provides a Model Context Protocol (MCP) server, built with Express and deployed as a Netlify Function. It allows AI agents (like Langflow agents, Claude, Cursor, etc.) to interact with a self-hosted OpenProject instance via defined tools.

This example demonstrates:

• Setting up an MCP server using @modelcontextprotocol/sdk.
• Integrating with an external API (OpenProject).
• Deploying the MCP server serverlessly using Netlify Functions.
• Handling environment variables securely in Netlify.
• Providing a bridge for remote SSE clients (like cloud-hosted Langflow) to connect to the stateless Netlify function via mcp-proxy and ngrok.
• Model Context Protocol (MCP)
• Docs: Netlify Functions

Implemented OpenProject Tools

The server exposes the following tools for interacting with OpenProject:

• Projects:
  • openproject-create-project: Creates a new project.
  • openproject-get-project: Retrieves a specific project by ID.
  • openproject-list-projects: Lists all projects (supports pagination).
  • openproject-update-project: Updates an existing project's details.
  • openproject-delete-project: Deletes a project.
• Tasks (Work Packages):
  • openproject-create-task: Creates a new task within a project.
  • openproject-get-task: Retrieves a specific task by ID.
  • openproject-list-tasks: Lists tasks, optionally filtered by project ID (supports pagination).
  • openproject-update-task: Updates an existing task (requires lockVersion).
  • openproject-delete-task: Deletes a task.

Prerequisites

• Node.js (v18 or later recommended)
• npm
• Netlify CLI (npm install -g netlify-cli)
• Python 3.10 or later (required for the mcp-proxy tool used for SSE bridging)
• pip (Python package installer)
• An OpenProject instance accessible via URL.
• An OpenProject API Key.
• (Optional) ngrok account and CLI for testing remote SSE clients.

Setup Instructions

1. Clone the repository:
   git clone git@github.com:jessebautista/mcp-openproject.git cd mcp-openproject
2. Install Node.js dependencies:
   npm install
3. Install Python mcp-proxy: (Ensure you have Python 3.10+ active)
   # Check your python version first if needed: python3 --version # Install mcp-proxy (using pip associated with Python 3.10+): python3.10 -m pip install mcp-proxy # Or python3.11, python3.12 etc. depending on your version # If pipx is installed and preferred: pipx install mcp-proxy

Local Development

1. Create Environment File:
   • Create a file named .env in the project root.
   • Add your OpenProject details:
   OPENPROJECT_API_KEY="your_openproject_api_key_here" OPENPROJECT_URL="https://your_openproject_instance.com" OPENPROJECT_API_VERSION="v3"
   • (Important): Ensure .env is listed in your .gitignore file to avoid committing secrets.
2. Run Netlify Dev Server:
   • This command starts a local server, loads variables from .env, and makes your function available.
   netlify dev
   • Your local MCP endpoint will typically be available at http://localhost:8888/mcp.
3. Test Locally with MCP Inspector:
   • In a separate terminal, run the MCP Inspector, pointing it to your local server via mcp-remote:
   npx @modelcontextprotocol/inspector npx mcp-remote@next http://localhost:8888/mcp
   • Open the Inspector URL (usually http://localhost:6274) in your browser.
   • Connect and use the "Tools" tab to test the OpenProject CRUD operations.

Deployment to Netlify

1. Set Environment Variables in Netlify UI:
   • Go to your site's dashboard on Netlify (https://app.netlify.com/sites/gilded-fudge-69ca2e/configuration/env).
   • Under "Environment variables", add the following variables (ensure they are available to "Functions"):
     • OPENPROJECT_API_KEY: Your OpenProject API key.
     • OPENPROJECT_URL: Your OpenProject instance URL (e.g., https://project.bautistavirtualrockstars.com).
     • OPENPROJECT_API_VERSION: v3
   • (Security): The code in netlify/mcp-server/index.ts reads these from process.env. The hardcoded values should be removed (already done in our steps).
2. Deploy via Git:
   • Commit your code changes:
   git add . git commit -m "Deploy OpenProject MCP server updates"
   • Push to the branch Netlify is configured to deploy (e.g., main):
   git push origin main
   • Netlify will automatically build and deploy the new version. Monitor progress in the "Deploys" section of your Netlify dashboard.

Testing Deployed Version

1. Using MCP Inspector:
   • Run the inspector, pointing mcp-remote to your live Netlify function URL:
   npx @modelcontextprotocol/inspector npx mcp-remote@next https://gilded-fudge-69ca2e.netlify.app/mcp
   • Open the Inspector URL and test the tools. Check Netlify function logs if errors occur.
2. Connecting Remote SSE Clients (e.g., Cloud-Hosted Langflow):
   • Since the Netlify function is stateless (doesn't handle SSE connections directly via GET), and remote clients like Langflow often prefer SSE, you need a bridge. We use the Python mcp-proxy tool combined with the JS mcp-remote tool, and ngrok for a public tunnel.
   • Step A: Start the Proxy Bridge Locally:
     • Run this command in a terminal on your local machine (ensure Python 3.10+ is active and mcp-proxy is installed):
     # Listen for SSE on local port 7865, run npx mcp-remote as the backend mcp-proxy --sse-port 7865 -- npx mcp-remote@next https://gilded-fudge-69ca2e.netlify.app/mcp
     • Keep this terminal running. Check its output to ensure it started listening and spawned the npx command.
   • Step B: Create a Public Tunnel with ngrok:
     • In a separate terminal, run ngrok to expose the local port mcp-proxy is listening on:
     ngrok http 7865
     • ngrok will display a public "Forwarding" URL (e.g., https://<random-string>.ngrok-free.app). Copy this HTTPS URL.
   • Step C: Configure Langflow:
     • In your Langflow MCP Connection component (running on https://lang.singforhope.org/):
       • Mode: SSE
       • MCP SSE URL: Paste the full ngrok public URL including the /sse path required by mcp-proxy (e.g., https://<random-string>.ngrok-free.app/sse).
     • Langflow should now be able to connect and use the tools via the ngrok -> mcp-proxy -> mcp-remote -> Netlify chain.
   • (Note): This ngrok setup is for testing/development. For a permanent solution, deploy the mcp-proxy bridge to a persistent public server.

Netlify Function Configuration (netlify.toml)

Ensure your netlify.toml correctly redirects requests to the /mcp path to your Express function handler:

(Adjust redirects as needed based on your Express routing)