diff --git a/FORGEJO_SETUP.md b/FORGEJO_SETUP.md
new file mode 100644
index 0000000..b431699
--- /dev/null
+++ b/FORGEJO_SETUP.md
@@ -0,0 +1,245 @@
+# Forgejo MCP Setup Guide
+
+This guide walks you through adding Forgejo-MCP to your MCP gateway.
+
+## Quick Start
+
+### 1. Prerequisites
+
+- Docker and Docker Compose installed
+- Forgejo instance running at `http://10.0.0.25:34577`
+- Forgejo API access token (you have this: `df0555d179c7ce6d11c6605b7ddad0921c3c4c83`)
+
+### 2. Update Environment Variables
+
+Add the following to your `.env` file in the `mcp-gateway` directory:
+
+```env
+# Forgejo Configuration
+FORGEJO_URL=http://10.0.0.25:34577
+FORGEJO_ACCESS_TOKEN=df0555d179c7ce6d11c6605b7ddad0921c3c4c83
+```
+
+### 3. Build and Deploy
+
+```bash
+cd /path/to/mcp-gateway
+
+# Build the Forgejo-MCP service
+docker-compose build forgejo-mcp
+
+# Start the service
+docker-compose up -d forgejo-mcp
+
+# Verify it's running
+docker-compose logs -f forgejo-mcp
+```
+
+### 4. Verify Integration
+
+The gateway should automatically discover the Forgejo-MCP service. Check the gateway logs:
+
+```bash
+docker-compose logs -f gateway
+```
+
+You should see a message like:
+```
+Backend configured: forgejo -> http://mcp-forgejo:8400/mcp
+```
+
+### 5. Test the Tools
+
+Using curl to test the gateway:
+
+```bash
+# List repositories (example)
+curl -X POST http://localhost:4444/call_tool \
+  -H "Authorization: Bearer YOUR_GATEWAY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "tool": "forgejo_list_repositories",
+    "arguments": {
+      "owner": "your-username"
+    }
+  }'
+```
+
+## Configuration Details
+
+### Forgejo API Token
+
+Your token has been provided: `df0555d179c7ce6d11c6605b7ddad0921c3c4c83`
+
+This token provides access to:
+- Repository operations
+- Issue management
+- Pull request management
+- User information
+- File reading
+
+**To create new tokens in Forgejo:**
+
+1. Log in to your Forgejo instance
+2. Go to Settings → Applications → Personal Access Tokens
+3. Click "New Token"
+4. Name: `MCP Gateway`
+5. Scopes:
+   - ✓ `repo` - Full repository access
+   - ✓ `read:user` - Read user information
+6. Click "Generate Token"
+7. Copy the token and add to `.env`
+
+### Port Configuration
+
+- **Forgejo-MCP Service**: Port `8400` (internal to Docker)
+- **MCP Gateway**: Port `4444` (exposed to host)
+- **Forgejo**: `http://10.0.0.25:34577` (local network)
+
+### Health Checks
+
+The Forgejo-MCP service includes health checks:
+
+```bash
+# Check service health
+docker-compose ps forgejo-mcp
+
+# Manual health check
+curl http://localhost:8400/health
+```
+
+## Available Tools
+
+After setup, the following tools will be available through the gateway:
+
+### Repository Management
+- `forgejo_list_repositories` - List user/org repositories
+- `forgejo_get_repository` - Get repository details
+- `forgejo_create_repository` - Create a new repository
+
+### Issue Management
+- `forgejo_list_issues` - List repository issues
+- `forgejo_create_issue` - Create a new issue
+- `forgejo_update_issue` - Update an issue
+
+### Pull Requests
+- `forgejo_list_pull_requests` - List pull requests
+- `forgejo_create_pull_request` - Create a pull request
+
+### Files & Branches
+- `forgejo_list_branches` - List repository branches
+- `forgejo_get_file` - Read file contents
+
+### Search & Users
+- `forgejo_search_repositories` - Search repositories
+- `forgejo_get_user` - Get user profile information
+
+## Troubleshooting
+
+### Service won't start
+
+Check logs:
+```bash
+docker-compose logs forgejo-mcp
+```
+
+Common issues:
+- **Port 8400 already in use**: Change `PORT` in docker-compose.yml
+- **Missing environment variables**: Verify `.env` file has `FORGEJO_ACCESS_TOKEN`
+- **Network issues**: Verify `10.0.0.25:34577` is reachable
+
+### Gateway can't connect to Forgejo-MCP
+
+```bash
+# Check service is running
+docker-compose ps forgejo-mcp
+
+# Check network connectivity
+docker exec mcp-gateway ping mcp-forgejo
+
+# Check gateway logs
+docker-compose logs gateway
+```
+
+### Authentication errors
+
+Verify your token:
+```bash
+# Test Forgejo API directly
+curl -H "Authorization: token df0555d179c7ce6d11c6605b7ddad0921c3c4c83" \
+  http://10.0.0.25:34577/api/v1/user
+```
+
+Should return your user information.
+
+### Tool returns empty results
+
+- Verify you have repositories in Forgejo
+- Check you're using correct owner name (username or org name)
+- Try with `limit: 50` to increase result count
+
+## Performance Considerations
+
+- **Pagination**: Tools support pagination with `limit` and `page` parameters
+- **Default limits**: Default limit is 20 items per request
+- **Large result sets**: Use pagination to retrieve more results
+- **API rate limiting**: Forgejo's rate limiting is not typically a concern for local instances
+
+## Security Best Practices
+
+1. **Token Management**
+   - Store token in `.env` (Git-ignored)
+   - Don't hardcode tokens in source files
+   - Periodically rotate tokens
+   - Use minimal scope tokens
+
+2. **Network Security**
+   - Use HTTPS for production Forgejo instances
+   - Restrict gateway access with authentication
+   - Use firewall rules to limit access to Forgejo
+
+3. **Monitoring**
+   - Monitor token usage logs
+   - Review gateway logs for errors
+   - Alert on authentication failures
+
+## Next Steps
+
+1. **Test the integration**: Use the gateway API to list repositories
+2. **Configure access**: Set up OAuth users if needed
+3. **Monitor**: Check logs for any issues
+4. **Extend**: Create additional workflows using Forgejo tools
+
+## Stopping the Service
+
+```bash
+# Stop just Forgejo-MCP
+docker-compose stop forgejo-mcp
+
+# Stop all services
+docker-compose down
+
+# Stop and remove volumes
+docker-compose down -v
+```
+
+## Updating the Service
+
+After making changes to the code:
+
+```bash
+# Rebuild
+docker-compose build forgejo-mcp
+
+# Restart
+docker-compose up -d forgejo-mcp
+
+# Check logs
+docker-compose logs -f forgejo-mcp
+```
+
+## Additional Resources
+
+- [Forgejo API Documentation](https://forgejo.org/docs/latest/api/)
+- [MCP Specification](https://modelcontextprotocol.io/)
+- [Gateway Configuration](./DEPLOYMENT_GUIDE.md)