diff --git a/PYPI_PUBLISHING.md b/PYPI_PUBLISHING.md
new file mode 100644
index 0000000..09f8b66
--- /dev/null
+++ b/PYPI_PUBLISHING.md
@@ -0,0 +1,200 @@
+# PyPI Publishing Setup Guide
+
+This guide explains how to set up and use the automated PyPI publishing workflow for the `vultr-dns-mcp` package.
+
+## 🔐 Setting Up Trusted Publishing (Recommended)
+
+The workflow uses [PyPI's trusted publishing](https://docs.pypi.org/trusted-publishers/) feature, which eliminates the need for API tokens. This is the most secure method.
+
+### For PyPI (Production)
+
+1. **Go to your project on PyPI**: https://pypi.org/manage/project/vultr-dns-mcp/
+2. **Navigate to "Publishing"** tab
+3. **Add a new trusted publisher** with these settings:
+   - **PyPI Project Name**: `vultr-dns-mcp`
+   - **Owner**: `rsp2k`
+   - **Repository name**: `vultr-dns-mcp`
+   - **Workflow filename**: `publish.yml`
+   - **Environment name**: `pypi`
+
+### For TestPyPI (Testing)
+
+1. **Go to TestPyPI**: https://test.pypi.org/manage/project/vultr-dns-mcp/
+2. **Navigate to "Publishing"** tab
+3. **Add a new trusted publisher** with these settings:
+   - **PyPI Project Name**: `vultr-dns-mcp`
+   - **Owner**: `rsp2k`
+   - **Repository name**: `vultr-dns-mcp`
+   - **Workflow filename**: `publish.yml`
+   - **Environment name**: `testpypi`
+
+### GitHub Environment Setup
+
+1. **Go to your repository settings**: https://github.com/rsp2k/vultr-dns-mcp/settings/environments
+2. **Create two environments**:
+   - `pypi` (for production releases)
+   - `testpypi` (for testing)
+3. **Optional**: Add protection rules to require manual approval for production releases
+
+## 🚀 How to Publish
+
+### Automatic Publishing (Recommended)
+
+1. **Update the version** in `pyproject.toml`:
+   ```toml
+   [project]
+   name = "vultr-dns-mcp"
+   version = "1.0.2"  # Increment this
+   ```
+
+2. **Commit your changes**:
+   ```bash
+   git add pyproject.toml
+   git commit -m "Bump version to 1.0.2"
+   git push
+   ```
+
+3. **Create and push a version tag**:
+   ```bash
+   git tag v1.0.2
+   git push origin v1.0.2
+   ```
+
+4. **The workflow will automatically**:
+   - Run all tests
+   - Build the package
+   - Publish to PyPI
+   - Create a GitHub release
+   - Test the published package
+
+### Manual Publishing
+
+You can also trigger publishing manually:
+
+1. **Go to Actions** → **Publish to PyPI**
+2. **Click "Run workflow"**
+3. **Choose options**:
+   - ✅ **Publish to TestPyPI**: Test your release first
+   - ✅ **Skip if version exists**: Avoid errors for existing versions
+
+## 📋 Publishing Checklist
+
+Before creating a release tag:
+
+- [ ] All tests are passing on the main branch
+- [ ] Version number is updated in `pyproject.toml`
+- [ ] `CHANGELOG.md` is updated with the new version
+- [ ] Documentation is up to date
+- [ ] No breaking changes without major version bump
+
+## 🔄 Version Numbering
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** version: incompatible API changes (`2.0.0`)
+- **MINOR** version: new functionality, backwards compatible (`1.1.0`)
+- **PATCH** version: bug fixes, backwards compatible (`1.0.1`)
+
+### Pre-release Versions
+
+The workflow automatically detects pre-releases:
+- `1.0.0a1` (alpha)
+- `1.0.0b1` (beta)
+- `1.0.0rc1` (release candidate)
+- `1.0.0.dev1` (development)
+
+Pre-releases are marked as "pre-release" on GitHub.
+
+## 📝 Changelog Format
+
+The workflow automatically extracts changelog entries. Format your `CHANGELOG.md` like this:
+
+```markdown
+# Changelog
+
+## [1.0.2] - 2025-01-15
+
+### Added
+- New feature X
+- Support for Y
+
+### Fixed
+- Bug in Z functionality
+
+### Changed
+- Improved performance of A
+
+## [1.0.1] - 2025-01-10
+
+### Fixed
+- Critical bug fix
+```
+
+## 🔧 Alternative: API Token Method
+
+If you prefer using API tokens instead of trusted publishing:
+
+1. **Generate API tokens**:
+   - PyPI: https://pypi.org/manage/account/token/
+   - TestPyPI: https://test.pypi.org/manage/account/token/
+
+2. **Add secrets to repository**:
+   - Go to repository **Settings** → **Secrets and variables** → **Actions**
+   - Add `PYPI_API_TOKEN` and `TEST_PYPI_API_TOKEN`
+
+3. **Modify the workflow** to use tokens instead of trusted publishing.
+
+## 🛠️ Troubleshooting
+
+### Common Issues
+
+**"Version already exists"**: 
+- PyPI doesn't allow overwriting versions
+- Increment the version number in `pyproject.toml`
+
+**"Trusted publisher not configured"**:
+- Ensure you've set up trusted publishing correctly
+- Check the environment names match exactly
+
+**"Tests failing"**:
+- The workflow requires all validation tests to pass
+- Fix any failing tests before tagging
+
+**"Tag doesn't match version"**:
+- Ensure the git tag matches the version in `pyproject.toml`
+- Tag: `v1.0.2` should match version: `1.0.2`
+
+### Manual Testing
+
+Test your package locally before publishing:
+
+```bash
+# Install in development mode
+pip install -e .[dev,test]
+
+# Run the validation that the CI uses
+python run_tests.py --validate
+python run_tests.py --type unit
+python run_tests.py --lint
+
+# Build and check the package
+python -m build
+python -m twine check dist/*
+```
+
+## 📊 Monitoring
+
+After publishing, monitor:
+- **PyPI downloads**: https://pypistats.org/packages/vultr-dns-mcp
+- **GitHub releases**: https://github.com/rsp2k/vultr-dns-mcp/releases
+- **Actions logs**: https://github.com/rsp2k/vultr-dns-mcp/actions
+
+## 🎯 Next Steps
+
+1. Set up trusted publishing on PyPI and TestPyPI
+2. Create your first release by tagging `v1.0.1`
+3. Monitor the workflow execution
+4. Set up branch protection rules if desired
+5. Consider adding dependabot for automated dependency updates
+
+The workflow is designed to be secure, robust, and easy to use. It follows Python packaging best practices and provides comprehensive validation before publishing.