tendril/kb/_guides/CURSOR_WINDOWS_SETUP.md

Gitea Development Environment Setup Guide for Windows & Cursor

Objective: This document details the complete process for configuring a local development environment on a Windows PC to work with a Gitea-hosted source code repository. It covers connecting the Cursor IDE using the Model Context Protocol (MCP) and cloning a project repository to begin work.

Core Components

• Gitea: The remote Git server where the project's code is stored.

• Gitea MCP Server: A command-line application that acts as a bridge between Cursor and Gitea.

• Cursor IDE: The code editor used for development.

• Git for Windows: The underlying version control software used for all git commands.

---

Phase 1: Environment Setup and Configuration

Step 1: Download and Prepare the Gitea MCP Server

The first step is to get the bridge application that allows Cursor to communicate with Gitea.

1. Download the Binary:

   • Navigate to the official Gitea MCP releases page: https://gitea.com/gitea/gitea-mcp/releases

   • From the latest release, download the zip archive for Windows, named gitea-mcp_Windows_x86_64.zip.

2. Create a Permanent Location:

   • Create a dedicated folder on your computer where this tool will live permanently. For this guide, we used: D:\OneDrive\GIT_Parkingmeter\gitea-mcp_Windows_x86_64

3. Extract the Files:

   • Extract the contents of the downloaded .zip file into the folder you just created. The most important file is gitea-mcp.exe.

Step 2: Generate a Gitea Access Token

Cursor needs a secure "password" to access your Gitea account. This is called an Access Token.

1. Navigate to Gitea Settings: Go to your Gitea instance's Applications page: https://git.parkingmeter.info/user/settings/applications

2. Generate a New Token:

   • Give the token a descriptive name (e.g., "Cursor on Windows PC").

   • Set the following permissions to Read and Write:

     • issue

     • repository

     • user

   • Click "Generate Token".

3. Copy and Save the Token:

   • CRITICAL: Gitea will display the token only once. Copy it immediately and save it in a secure place (like a password manager or a temporary text file). You will need it in the next steps.

Step 3: Create the Server Startup Script (run-gitea.bat)

To ensure the Gitea MCP Server starts reliably every time, we will create a simple startup script.

1. Create the File:

   • In the same folder where you extracted gitea-mcp.exe, create a new file named run-gitea.bat.

2. Edit the Script:

   • Open run-gitea.bat with a text editor (like Notepad) and paste the following content:

   @echo off
   echo Starting Gitea MCP server in HTTP mode...
   echo Do not close this window!
   D:\OneDrive\GIT_Parkingmeter\gitea-mcp_Windows_x86_64\gitea-mcp.exe -t http --host https://git.parkingmeter.info --token YOUR_GITEA_TOKEN_HERE
   

3. Add Your Token:

   • In the script, replace YOUR_GITEA_TOKEN_HERE with the actual Gitea token you copied in Step 2.

   • Save and close the file.

Step 4: Configure Cursor's MCP Tools

This is the most important step. We need to tell Cursor how to find and use your new Gitea server.

1. Open Cursor's MCP Settings:

   • In Cursor, navigate to the settings UI.

   • Go to the "Tools & MCP" section.

   • You will see a file named mcp.json. Open this file.

2. Add the Gitea Server Configuration:

   • Inside the "mcpServers": { ... } object, add the following configuration block. Be sure to add a comma , after the preceding entry.

       "gitea-local": {
         "url": "http://localhost:8080/mcp",
         "headers": {
           "Authorization": "Bearer YOUR_GITEA_TOKEN_HERE"
         }
       }
   

3. Add Your Token:

   • Again, replace YOUR_GITEA_TOKEN_HERE with your actual Gitea token.

   • IMPORTANT: The word Bearer followed by a space must be kept in front of the token.

4. Save the mcp.json file.

Step 5: Test the Connection Workflow

This is the process you will follow each time you want to use the Gitea integration.

1. Manually Start the Server:

   • Using File Explorer, navigate to your gitea-mcp_Windows_x86_64 folder.

   • Double-click the run-gitea.bat script.

   • A black command prompt window will appear and stay open. This is your server. You must keep this window running while you use the integration in Cursor.

2. Restart and Test in Cursor:

   • Completely close and reopen the Cursor application to ensure it loads the new configuration.

   • Open the AI Chat panel (Ctrl + L).

   • Send the command: @gitea-local list my repositories.

   • The AI may initially be confused. Confirm that it should make a direct API call to your Gitea instance, providing the URL (https://git.parkingmeter.info) when prompted.

   • Success is confirmed when the AI returns a formatted list of your Gitea repositories.

Step 6: Clone the Project Repository

The final setup step is to download the project's source code to your machine.

1. Open a Terminal in Cursor:

   • Go to the top menu and select Terminal -> New Terminal.

2. Navigate to Your Projects Directory:

   • In the terminal, change to the folder where you want to store your projects. We used:

     cd /d/OneDrive/GIT_Parkingmeter
     

3. Clone the Repository:

   • Run the git clone command with the project's URL:

     git clone https://git.parkingmeter.info/Mycelium/tendril.git
     

---

Phase One Complete

At this point, your environment is fully configured. You have successfully linked Cursor to your Gitea account and downloaded a local copy of the project code. You are now ready to move on to Phase Two: The Development Workflow (editing, pushing, and pulling code).