Tendril: Gitea MCP for Zed

A Zed IDE extension that integrates with Gitea through the Model Context Protocol (MCP). Tendril is part of The Mycelium Project and provides seamless access to Gitea repositories, issues, pull requests, and more directly within your editor.

What is This?

Tendril is a Zed IDE extension that acts as a bridge between Zed and a Gitea MCP server. The extension is lightweight - it connects your editor to a Gitea MCP server running on your system (or in Docker).

Think of it as:

• Extension: Tendril (this repository) - runs inside Zed
• Server: gitea-mcp binary or Docker container - communicates with Gitea
• Result: Full Gitea access from your editor through Zed's AI features

Requirements

Before you can use Tendril, you need:

1. Zed IDE - Download from https://zed.dev
2. Gitea MCP Server - Either:
   • Binary installed locally, OR
   • Docker with gitea-mcp image
3. Gitea Access Token - Generated from your Gitea instance
4. Rust (for dev installation) - Installed via rustup

Quick Start

Step 1: Install Gitea MCP Server

Choose one method:

Option A: macOS (Homebrew - Recommended)

brew install gitea/tap/gitea-mcp-server

The binary will be installed at /opt/homebrew/bin/gitea-mcp-server.

Option B: Linux (Pre-built Binary)

# Download from: https://gitea.com/gitea/gitea-mcp/releases
# Example for Linux x64:
wget https://gitea.com/gitea/gitea-mcp/releases/download/v1.0.0/gitea-mcp-linux-amd64
chmod +x gitea-mcp-linux-amd64
sudo mv gitea-mcp-linux-amd64 /usr/local/bin/gitea-mcp

Option C: Build from Source

git clone https://gitea.com/gitea/gitea-mcp.git
cd gitea-mcp
make install

Option D: Use Docker

If you prefer Docker, skip the binary installation - we'll configure Docker mode in Step 3.

Step 2: Generate a Gitea Access Token

1. Log in to your Gitea instance
2. Go to Settings → Applications → Generate New Token
3. Give it a name like "Zed MCP"
4. Select repository-related permissions
5. Copy the token

Step 3: Install Tendril Extension

1. Clone this repository
2. Open Zed
3. Go to Extensions panel (Cmd/Ctrl + Shift + X)
4. Click Install Dev Extension
5. Select the tendril directory
6. Zed will compile and load the extension

Step 4: Configure Zed Settings

Open your Zed settings (Cmd/Ctrl + ,) and add one of the following configurations:

For Local Binary (macOS with Homebrew):

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE",
        "gitea_mcp_binary_path": "/opt/homebrew/bin/gitea-mcp-server"
      }
    }
  }
}

For Local Binary (Linux):

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE",
        "gitea_mcp_binary_path": "/usr/local/bin/gitea-mcp"
      }
    }
  }
}

For Docker:

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_GITEA_TOKEN_HERE",
        "use_docker": true,
        "docker_binary_path": "/usr/bin/docker"
      }
    }
  }
}

Note: Find your docker path with which docker and use that full path.

Step 5: Test the Connection

In Zed's Assistant panel, try:

list my repositories

You should see your Gitea repositories!

Configuration Reference

Required Settings

Setting	Type	Description
gitea_access_token	string	Your Gitea personal access token

Binary Configuration (choose one)

Setting	Type	Description
gitea_mcp_binary_path	string	Full path to gitea-mcp binary (e.g., /opt/homebrew/bin/gitea-mcp-server)
use_docker	boolean	Set to true to use Docker instead of local binary
docker_binary_path	string	Full path to docker binary (required when use_docker: true)

Important: Due to WebAssembly sandbox limitations, you must explicitly configure:

• Either gitea_mcp_binary_path for local binary
• Or use_docker: true + docker_binary_path for Docker mode

Auto-detection is not possible.

Optional Settings

Setting	Type	Default	Description
gitea_host	string	(none)	URL of your Gitea instance (for self-hosted)
gitea_insecure	boolean	false	Allow self-signed certificates
docker_image	string	gitea/gitea-mcp-server:latest	Docker image to use (when use_docker: true)

Finding binary paths:

• gitea-mcp: which gitea-mcp or which gitea-mcp-server
• docker: which docker

Configuration Examples

Self-Hosted Gitea with Binary

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_TOKEN",
        "gitea_host": "https://git.example.com",
        "gitea_mcp_binary_path": "/usr/local/bin/gitea-mcp"
      }
    }
  }
}

Self-Hosted Gitea with Docker

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_TOKEN",
        "gitea_host": "https://git.example.com",
        "use_docker": true,
        "docker_binary_path": "/usr/bin/docker"
      }
    }
  }
}

Self-Signed Certificates

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_TOKEN",
        "gitea_host": "https://git.internal.company.com",
        "gitea_insecure": true,
        "gitea_mcp_binary_path": "/usr/local/bin/gitea-mcp"
      }
    }
  }
}

Security Note: Only use gitea_insecure: true for trusted internal servers.

Custom Docker Image

{
  "context_servers": {
    "tendril-gitea-mcp": {
      "settings": {
        "gitea_access_token": "YOUR_TOKEN",
        "use_docker": true,
        "docker_binary_path": "/usr/bin/docker",
        "docker_image": "my-registry.com/gitea-mcp:v1.0.0"
      }
    }
  }
}

Available Features

Through the Gitea MCP server, you get access to:

• User Management: Get user info, list organizations, search users
• Repository Management: List, create, fork repositories
• Branch Management: Create, delete, list branches
• Release Management: Create, list, delete releases
• Tag Management: Create, list, delete tags
• File Operations: View, create, update, delete files
• Issue Management: Create, edit, list issues, add comments
• Pull Requests: Create, list, manage pull requests
• Commits: List and view commits

See the Gitea MCP documentation for complete tool details.

Why Explicit Configuration?

Tendril runs as a WebAssembly (WASM) extension inside Zed. The WASM sandbox has important security restrictions:

• ❌ Cannot detect the host operating system
• ❌ Cannot access PATH environment variable reliably (especially on macOS)
• ❌ Cannot check if files exist on the filesystem
• ❌ Cannot spawn commands like which

These limitations mean automatic binary discovery is unreliable and platform-dependent. Explicit configuration ensures the extension works reliably across all platforms.

The upside: Once configured, it just works! And you have full control over which binary/Docker image is used.

Note on Docker: Docker mode also requires explicit docker_binary_path for the same reasons.

Troubleshooting

"Binary path not configured" Error

You'll see this if neither gitea_mcp_binary_path nor use_docker is set.

Solution: Add one of these to your Zed settings:

"gitea_mcp_binary_path": "/opt/homebrew/bin/gitea-mcp-server"

or

"use_docker": true,
"docker_binary_path": "/usr/bin/docker"

Finding Your Binary Path

If you're not sure where your binary is installed:

macOS (Homebrew):

which gitea-mcp-server
# Output: /opt/homebrew/bin/gitea-mcp-server

Linux:

which gitea-mcp
# Output: /usr/local/bin/gitea-mcp

Use the output path in your gitea_mcp_binary_path setting.

"Failed to spawn command" Error

The path is configured but Zed can't execute the binary:

1. Verify the path is correct:

   ls -la /opt/homebrew/bin/gitea-mcp-server
   

2. Ensure it's executable:

   chmod +x /opt/homebrew/bin/gitea-mcp-server
   

3. Test it manually:

   /opt/homebrew/bin/gitea-mcp-server --help
   

4. Restart Zed after fixing permissions

Authentication Issues

• Verify your token has the correct permissions
• Check for extra spaces when copying the token
• Ensure the token hasn't expired
• Try generating a new token

Docker Issues

If using use_docker: true and seeing errors:

1. Find your docker binary path:

   which docker
   # Output: /usr/bin/docker (use this in docker_binary_path)
   

2. Check Docker is running:

   docker ps
   

3. Verify Docker can pull images:

   docker pull gitea/gitea-mcp-server:latest
   

4. On Linux, check permissions:

   sudo usermod -aG docker $USER
   # Log out and back in
   

Common Docker paths:

• Linux: /usr/bin/docker
• macOS: /usr/local/bin/docker or /Applications/Docker.app/Contents/Resources/bin/docker

View Logs

Check Zed logs for detailed error messages:

1. In Zed, run command: zed: open log
2. Look for errors related to "tendril" or "gitea-mcp"
3. The error messages will show the exact path that was attempted

Development

Building from Source

Prerequisites:

• Rust (installed via rustup)
• WASM target: rustup target add wasm32-unknown-unknown

Build the extension:

cd tendril
cargo build --target wasm32-unknown-unknown --release
cp target/wasm32-unknown-unknown/release/mcp_server_gitea.wasm extension.wasm

Project Structure

tendril/
├── Cargo.toml                          # Rust project configuration
├── extension.toml                      # Zed extension manifest
├── src/
│   └── mcp_server_gitea.rs            # Main extension logic
├── configuration/
│   ├── default_settings.jsonc         # Default configuration template
│   └── installation_instructions.md   # Setup guide for Zed UI
├── README.md                           # This file
├── DEVELOPMENT.md                      # Developer guide
├── PROJECT_STATUS.md                   # Project status and roadmap
└── LICENSE                             # Apache 2.0

Code Overview

The extension is ~300 lines of clean Rust code:

• GiteaContextServerSettings: Configuration structure
• build_binary_command(): Creates command for local binary
• build_docker_command(): Creates command for Docker
• resolve_binary_path(): Validates explicit configuration

Common Binary Paths

For reference, here are the typical installation paths:

Platform	Package Manager	Path
macOS	Homebrew	/opt/homebrew/bin/gitea-mcp-server
macOS (Intel)	Homebrew	/usr/local/bin/gitea-mcp-server
Linux	Manual install	/usr/local/bin/gitea-mcp
Linux	User install	~/.local/bin/gitea-mcp
Source build	Cargo	~/.cargo/bin/gitea-mcp
Windows	Manual install	C:\Program Files\gitea-mcp\gitea-mcp.exe

Use which gitea-mcp or which gitea-mcp-server to find your actual path.

Related Projects

• Gitea: https://gitea.io - Lightweight Git service
• Gitea MCP: https://gitea.com/gitea/gitea-mcp - MCP server for Gitea
• Model Context Protocol: https://modelcontextprotocol.io
• The Mycelium Project: https://git.parkingmeter.info/Mycelium
• Zed IDE: https://zed.dev

License

Licensed under the Apache License 2.0. See LICENSE for details.

Support

For issues or questions:

1. Check troubleshooting section above
2. Review Zed logs using zed: open log
3. Open an issue on Tendril repository
4. Consult documentation:
   • Zed Extensions
   • Gitea MCP
   • Model Context Protocol

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for detailed guidelines on:

• Development workflow
• Branch management
• Documentation standards
• Code quality requirements
• Pull request process

Quick Start:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes and test thoroughly
4. Submit a pull request with a clear description

For full details, see CONTRIBUTING.md.

Authors

• Ryan Parmeter (@parkingmeter)
• The Mycelium Project Contributors

Changelog

v0.2.0 (Current)

• 🔧 BREAKING: Removed automatic binary path detection (WASM limitations)
• ✨ Explicit configuration required: gitea_mcp_binary_path or use_docker: true + docker_binary_path
• ✨ Docker mode now requires explicit docker_binary_path (consistent with binary requirement)
• 📚 Simplified documentation and clearer error messages
• 🐛 Fixed macOS M4 compatibility issues
• ✅ Tested on Linux (x86_64) and macOS (M4)

v0.1.0 (Previous)

• ✨ Attempted automatic binary path detection
• ✨ Docker support
• 🐛 Issues with PATH detection in WASM on macOS

v0.0.1 (Initial)

• Initial development version
• STDIO mode support
• Basic configuration through Zed settings