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:

Zed IDE - Download from https://zed.dev
Gitea MCP Server - Either:
- Binary installed locally, OR
- Docker with gitea-mcp image
Gitea Access Token - Generated from your Gitea instance
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

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

Step 3: Install Tendril Extension

Clone this repository
Open Zed
Go to Extensions panel (Cmd/Ctrl + Shift + X)
Click Install Dev Extension
Select the tendril directory
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"

"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:

Verify the path is correct:

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

Ensure it's executable:

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

Test it manually:

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

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:

Find your docker binary path:

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

Check Docker is running:
```
docker ps
```

Verify Docker can pull images:

docker pull gitea/gitea-mcp-server:latest

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:

In Zed, run command: zed: open log
Look for errors related to "tendril" or "gitea-mcp"
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.

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:

Check troubleshooting section above
Review Zed logs using zed: open log
Open an issue on Tendril repository
Consult documentation:

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Make your changes and test thoroughly
Submit a pull request with a clear description

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

README.md

Tendril: Gitea MCP for Zed