# Strands MCP Server
[](https://github.com/strands-agents/strands-mcp-server/actions)
[](https://badge.fury.io/py/strands-mcp-server)
[](https://www.python.org/downloads/)
A Model Context Protocol (MCP) server that provides semantic search capabilities for the Strands Agent SDK documentation. This server enables AI assistants and development tools to access up-to-date Strands SDK documentation through intelligent search and retrieval.
## Features
- **Semantic Documentation Search**: Fast, intelligent search across Strands SDK documentation
- **Bundled Cache**: Pre-built documentation cache for immediate availability
- **Background Updates**: Automatic documentation updates with configurable intervals
- **Fast Startup**: Instant search capabilities using bundled cache
- **GitHub Integration**: Fetches latest documentation from Strands repositories
- **Health Monitoring**: Built-in health checks and error handling
- **MCP Compatible**: Works with any MCP-compatible client (Claude Desktop, Kiro IDE, etc.)
## Quick Start
### Installation
```bash
# Install from PyPI
pip install strands-mcp-server
# Or install with uv (recommended)
uv add strands-mcp-server
```
### Basic Usage
#### With Claude Desktop
Add to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"strands-docs": {
"command": "python",
"args": ["-m", "strands_mcp.main"],
"env": {
"GITHUB_TOKEN": "your_github_token_here"
}
}
}
}
```
#### With Kiro IDE
Add to your Kiro MCP configuration (`.kiro/settings/mcp.json`):
```json
{
"mcpServers": {
"strands-docs": {
"command": "uvx",
"args": ["strands-mcp-server@latest"],
"env": {
"GITHUB_TOKEN": "your_github_token_here"
},
"disabled": false,
"autoApprove": ["search_documentation", "list_documentation"]
}
}
}
```
#### Direct Usage
```bash
# Run the MCP server directly
python -m strands_mcp.main
# Or with uvx
uvx strands-mcp-server@latest
```
## Configuration
### Environment Variables
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `GITHUB_TOKEN` | GitHub personal access token for API access | Recommended | None |
| `CACHE_DIR` | Directory for storing cached documentation | No | User cache dir |
| `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | No | INFO |
| `UPDATE_INTERVAL` | Background update interval in hours | No | 24 |
### GitHub Token Setup
A GitHub token is recommended to avoid API rate limits when fetching documentation.
#### Creating a GitHub Token
1. Go to [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)
2. Click "Generate new token (classic)"
3. Give it a descriptive name like "Strands MCP Server"
4. Select scopes: `public_repo` (for accessing public repositories)
5. Click "Generate token"
6. Copy the token (you won't see it again!)
#### Setting the Token
**Quick Setup (Recommended):**
```bash
# Use the built-in setup utility
strands-setup-token
# Or with pip/uvx
pip install strands-mcp-server
strands-setup-token
```
**Manual Setup:**
```bash
# Option 1: Environment variable
export GITHUB_TOKEN=ghp_your_token_here
# Option 2: In your shell profile (.bashrc, .zshrc, etc.)
echo 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.zshrc
# Option 3: In MCP configuration (see examples above)
```
**For Production/CI:**
- Use GitHub repository secrets (see [GitHub Secrets Setup Guide](docs/GITHUB_SECRETS_SETUP.md))
- Use environment-specific secret management
- Never commit tokens to source control
## Available Tools
The MCP server provides the following tools:
### `search_documentation`
Search Strands SDK documentation using semantic search.
**Parameters:**
- `query` (string): Search query
- `limit` (integer, optional): Maximum results (default: 10, max: 50)
- `min_score` (number, optional): Minimum relevance score (default: 0.3)
**Example:**
```json
{
"name": "search_documentation",
"arguments": {
"query": "how to create a multi-agent workflow",
"limit": 5,
"min_score": 0.5
}
}
```
### `list_documentation`
Browse available documentation sections and documents.
**Parameters:**
- `section_filter` (string, optional): Filter by section name
- `limit` (integer, optional): Maximum results (default: 20, max: 100)
**Example:**
```json
{
"name": "list_documentation",
"arguments": {
"section_filter": "multi-agent",
"limit": 10
}
}
```
### Health Check Tools
- `health_check`: Check server health status
- `readiness_check`: Check if server is ready to serve requests
- `liveness_check`: Check if server is alive and responsive
## Development
### Prerequisites
- Python 3.11 or higher
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- Git
### Setup
```bash
# Clone the repository
git clone https://github.com/strands-agents/strands-mcp-server.git
cd strands-mcp-server
# Install dependencies with uv
uv sync
# Or with pip
pip install -e ".[dev]"
# Set up pre-commit hooks (optional)
pre-commit install
```
### Setting Up GitHub Token
For development, you'll need a GitHub token to avoid rate limits:
```bash
# Use the setup utility (recommended)
uv run strands-setup-token
# Or set manually
export GITHUB_TOKEN=your_token_here
```
### Building Documentation Cache
The server includes a bundled documentation cache, but you can rebuild it:
```bash
# Build with GitHub token (recommended)
GITHUB_TOKEN=your_token python scripts/build_bundled_cache.py --force
# Build without token (rate limited)
python scripts/build_bundled_cache.py --force
# Verbose output
python scripts/build_bundled_cache.py --force --verbose
```
### Running Tests
```bash
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=strands_mcp --cov-report=html
# Run specific test categories
uv run pytest tests/unit/ # Unit tests only
uv run pytest tests/integration/ # Integration tests only
```
### Code Quality
```bash
# Format code
uv run black src/ tests/
# Lint code
uv run ruff check src/ tests/
# Type checking
uv run mypy src/
```
## CI/CD and GitHub Token Access
### Repository Secrets
For automated builds and deployments, configure these GitHub repository secrets:
1. Go to your repository Settings > Secrets and variables > Actions
2. Add the following secrets:
| Secret Name | Description | Value |
|-------------|-------------|-------|
| `GITHUB_TOKEN` | GitHub token for documentation access | `ghp_your_token_here` |
| `PYPI_API_TOKEN` | PyPI token for package publishing | `pypi-your_token_here` |
### GitHub Actions Workflows
The repository includes automated workflows:
#### Build and Test (`ci.yml`)
- Runs on every push and pull request
- Tests across multiple Python versions
- Builds documentation cache
- Runs code quality checks
#### Publish to PyPI (`publish.yml`)
- Runs on new releases
- Builds and publishes package to PyPI
- Uses trusted publishing (no manual tokens needed)
#### Update Documentation Cache (`update-cache.yml`)
- Runs daily to update bundled documentation
- Creates pull requests with updated cache
- Ensures documentation stays current
### Manual Workflow Triggers
You can manually trigger workflows:
```bash
# Trigger cache update
gh workflow run update-cache.yml
# Trigger build and test
gh workflow run ci.yml
# Trigger publish (requires release)
gh workflow run publish.yml
```
## Architecture
### Cache Hierarchy
The server uses a multi-level cache system:
1. **Bundled Cache**: Pre-built cache included in the package
2. **User Cache**: Local cache updated in the background
3. **Memory Cache**: In-memory cache for frequently accessed data
### Documentation Sources
- **Primary**: [Strands Agent SDK Documentation](https://github.com/strands-agents/docs)
- **Fallback**: Bundled cache included with the package
- **Updates**: Automatic background updates from GitHub
## Troubleshooting
### Common Issues
#### "No documentation found" or empty search results
- Check if GitHub token is configured correctly
- Verify internet connectivity
- Try rebuilding the cache: `python scripts/build_bundled_cache.py --force`
#### Rate limit errors
- Add a GitHub token to your configuration
- Check token permissions (needs `public_repo` scope)
- Wait for rate limit to reset (usually 1 hour)
#### MCP connection issues
- Verify MCP client configuration
- Check server logs for error messages
- Ensure Python path is correct in MCP config
#### Import or module errors
- Reinstall the package: `pip install --force-reinstall strands-mcp-server`
- Check Python version compatibility (3.11+ required)
- Verify virtual environment activation
### Debug Mode
Enable debug logging for troubleshooting:
```bash
# Environment variable
export LOG_LEVEL=DEBUG
# Or in MCP configuration
{
"env": {
"LOG_LEVEL": "DEBUG"
}
}
```
### Getting Help
- **Issues**: [GitHub Issues](https://github.com/strands-agents/strands-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/strands-agents/strands-mcp-server/discussions)
- **Documentation**: [Strands Agent SDK Docs](https://github.com/strands-agents/docs)
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Workflow
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Add tests for new functionality
5. Run tests and ensure they pass
6. Commit your changes: `git commit -m 'Add amazing feature'`
7. Push to your branch: `git push origin feature/amazing-feature`
8. Open a Pull Request
### Code Standards
- Follow PEP 8 style guidelines
- Add type hints for all functions
- Write docstrings for public APIs
- Include tests for new features
- Update documentation as needed
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
---
**Built with ❤️ for the Strands Agent SDK community**
Raw data
{
"_id": null,
"home_page": null,
"name": "patersr-strands-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "agents, documentation, llm, mcp, strands",
"author": null,
"author_email": "Rob Paterson <your-email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/26/ef/d3bc627e1f12dd5c18ccd2a8d71d854b1b2edb01864916e303886890f97a/patersr_strands_mcp_server-0.2.5.tar.gz",
"platform": null,
"description": "# Strands MCP Server\n\n[](https://github.com/strands-agents/strands-mcp-server/actions)\n[](https://badge.fury.io/py/strands-mcp-server)\n[](https://www.python.org/downloads/)\n\nA Model Context Protocol (MCP) server that provides semantic search capabilities for the Strands Agent SDK documentation. This server enables AI assistants and development tools to access up-to-date Strands SDK documentation through intelligent search and retrieval.\n\n## Features\n\n- **Semantic Documentation Search**: Fast, intelligent search across Strands SDK documentation\n- **Bundled Cache**: Pre-built documentation cache for immediate availability\n- **Background Updates**: Automatic documentation updates with configurable intervals\n- **Fast Startup**: Instant search capabilities using bundled cache\n- **GitHub Integration**: Fetches latest documentation from Strands repositories\n- **Health Monitoring**: Built-in health checks and error handling\n- **MCP Compatible**: Works with any MCP-compatible client (Claude Desktop, Kiro IDE, etc.)\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install from PyPI\npip install strands-mcp-server\n\n# Or install with uv (recommended)\nuv add strands-mcp-server\n```\n\n### Basic Usage\n\n#### With Claude Desktop\n\nAdd to your Claude Desktop MCP configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):\n\n```json\n{\n \"mcpServers\": {\n \"strands-docs\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"strands_mcp.main\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"your_github_token_here\"\n }\n }\n }\n}\n```\n\n#### With Kiro IDE\n\nAdd to your Kiro MCP configuration (`.kiro/settings/mcp.json`):\n\n```json\n{\n \"mcpServers\": {\n \"strands-docs\": {\n \"command\": \"uvx\",\n \"args\": [\"strands-mcp-server@latest\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"your_github_token_here\"\n },\n \"disabled\": false,\n \"autoApprove\": [\"search_documentation\", \"list_documentation\"]\n }\n }\n}\n```\n\n#### Direct Usage\n\n```bash\n# Run the MCP server directly\npython -m strands_mcp.main\n\n# Or with uvx\nuvx strands-mcp-server@latest\n```\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required | Default |\n|----------|-------------|----------|---------|\n| `GITHUB_TOKEN` | GitHub personal access token for API access | Recommended | None |\n| `CACHE_DIR` | Directory for storing cached documentation | No | User cache dir |\n| `LOG_LEVEL` | Logging level (DEBUG, INFO, WARNING, ERROR) | No | INFO |\n| `UPDATE_INTERVAL` | Background update interval in hours | No | 24 |\n\n### GitHub Token Setup\n\nA GitHub token is recommended to avoid API rate limits when fetching documentation.\n\n#### Creating a GitHub Token\n\n1. Go to [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)\n2. Click \"Generate new token (classic)\"\n3. Give it a descriptive name like \"Strands MCP Server\"\n4. Select scopes: `public_repo` (for accessing public repositories)\n5. Click \"Generate token\"\n6. Copy the token (you won't see it again!)\n\n#### Setting the Token\n\n**Quick Setup (Recommended):**\n```bash\n# Use the built-in setup utility\nstrands-setup-token\n\n# Or with pip/uvx\npip install strands-mcp-server\nstrands-setup-token\n```\n\n**Manual Setup:**\n```bash\n# Option 1: Environment variable\nexport GITHUB_TOKEN=ghp_your_token_here\n\n# Option 2: In your shell profile (.bashrc, .zshrc, etc.)\necho 'export GITHUB_TOKEN=ghp_your_token_here' >> ~/.zshrc\n\n# Option 3: In MCP configuration (see examples above)\n```\n\n**For Production/CI:**\n- Use GitHub repository secrets (see [GitHub Secrets Setup Guide](docs/GITHUB_SECRETS_SETUP.md))\n- Use environment-specific secret management\n- Never commit tokens to source control\n\n## Available Tools\n\nThe MCP server provides the following tools:\n\n### `search_documentation`\nSearch Strands SDK documentation using semantic search.\n\n**Parameters:**\n- `query` (string): Search query\n- `limit` (integer, optional): Maximum results (default: 10, max: 50)\n- `min_score` (number, optional): Minimum relevance score (default: 0.3)\n\n**Example:**\n```json\n{\n \"name\": \"search_documentation\",\n \"arguments\": {\n \"query\": \"how to create a multi-agent workflow\",\n \"limit\": 5,\n \"min_score\": 0.5\n }\n}\n```\n\n### `list_documentation`\nBrowse available documentation sections and documents.\n\n**Parameters:**\n- `section_filter` (string, optional): Filter by section name\n- `limit` (integer, optional): Maximum results (default: 20, max: 100)\n\n**Example:**\n```json\n{\n \"name\": \"list_documentation\",\n \"arguments\": {\n \"section_filter\": \"multi-agent\",\n \"limit\": 10\n }\n}\n```\n\n### Health Check Tools\n\n- `health_check`: Check server health status\n- `readiness_check`: Check if server is ready to serve requests\n- `liveness_check`: Check if server is alive and responsive\n\n## Development\n\n### Prerequisites\n\n- Python 3.11 or higher\n- [uv](https://docs.astral.sh/uv/) (recommended) or pip\n- Git\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/strands-agents/strands-mcp-server.git\ncd strands-mcp-server\n\n# Install dependencies with uv\nuv sync\n\n# Or with pip\npip install -e \".[dev]\"\n\n# Set up pre-commit hooks (optional)\npre-commit install\n```\n\n### Setting Up GitHub Token\n\nFor development, you'll need a GitHub token to avoid rate limits:\n\n```bash\n# Use the setup utility (recommended)\nuv run strands-setup-token\n\n# Or set manually\nexport GITHUB_TOKEN=your_token_here\n```\n\n### Building Documentation Cache\n\nThe server includes a bundled documentation cache, but you can rebuild it:\n\n```bash\n# Build with GitHub token (recommended)\nGITHUB_TOKEN=your_token python scripts/build_bundled_cache.py --force\n\n# Build without token (rate limited)\npython scripts/build_bundled_cache.py --force\n\n# Verbose output\npython scripts/build_bundled_cache.py --force --verbose\n```\n\n### Running Tests\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=strands_mcp --cov-report=html\n\n# Run specific test categories\nuv run pytest tests/unit/ # Unit tests only\nuv run pytest tests/integration/ # Integration tests only\n```\n\n### Code Quality\n\n```bash\n# Format code\nuv run black src/ tests/\n\n# Lint code\nuv run ruff check src/ tests/\n\n# Type checking\nuv run mypy src/\n```\n\n## CI/CD and GitHub Token Access\n\n### Repository Secrets\n\nFor automated builds and deployments, configure these GitHub repository secrets:\n\n1. Go to your repository Settings > Secrets and variables > Actions\n2. Add the following secrets:\n\n| Secret Name | Description | Value |\n|-------------|-------------|-------|\n| `GITHUB_TOKEN` | GitHub token for documentation access | `ghp_your_token_here` |\n| `PYPI_API_TOKEN` | PyPI token for package publishing | `pypi-your_token_here` |\n\n### GitHub Actions Workflows\n\nThe repository includes automated workflows:\n\n#### Build and Test (`ci.yml`)\n- Runs on every push and pull request\n- Tests across multiple Python versions\n- Builds documentation cache\n- Runs code quality checks\n\n#### Publish to PyPI (`publish.yml`)\n- Runs on new releases\n- Builds and publishes package to PyPI\n- Uses trusted publishing (no manual tokens needed)\n\n#### Update Documentation Cache (`update-cache.yml`)\n- Runs daily to update bundled documentation\n- Creates pull requests with updated cache\n- Ensures documentation stays current\n\n### Manual Workflow Triggers\n\nYou can manually trigger workflows:\n\n```bash\n# Trigger cache update\ngh workflow run update-cache.yml\n\n# Trigger build and test\ngh workflow run ci.yml\n\n# Trigger publish (requires release)\ngh workflow run publish.yml\n```\n\n## Architecture\n\n### Cache Hierarchy\n\nThe server uses a multi-level cache system:\n\n1. **Bundled Cache**: Pre-built cache included in the package\n2. **User Cache**: Local cache updated in the background\n3. **Memory Cache**: In-memory cache for frequently accessed data\n\n### Documentation Sources\n\n- **Primary**: [Strands Agent SDK Documentation](https://github.com/strands-agents/docs)\n- **Fallback**: Bundled cache included with the package\n- **Updates**: Automatic background updates from GitHub\n\n## Troubleshooting\n\n### Common Issues\n\n#### \"No documentation found\" or empty search results\n- Check if GitHub token is configured correctly\n- Verify internet connectivity\n- Try rebuilding the cache: `python scripts/build_bundled_cache.py --force`\n\n#### Rate limit errors\n- Add a GitHub token to your configuration\n- Check token permissions (needs `public_repo` scope)\n- Wait for rate limit to reset (usually 1 hour)\n\n#### MCP connection issues\n- Verify MCP client configuration\n- Check server logs for error messages\n- Ensure Python path is correct in MCP config\n\n#### Import or module errors\n- Reinstall the package: `pip install --force-reinstall strands-mcp-server`\n- Check Python version compatibility (3.11+ required)\n- Verify virtual environment activation\n\n### Debug Mode\n\nEnable debug logging for troubleshooting:\n\n```bash\n# Environment variable\nexport LOG_LEVEL=DEBUG\n\n# Or in MCP configuration\n{\n \"env\": {\n \"LOG_LEVEL\": \"DEBUG\"\n }\n}\n```\n\n### Getting Help\n\n- **Issues**: [GitHub Issues](https://github.com/strands-agents/strands-mcp-server/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/strands-agents/strands-mcp-server/discussions)\n- **Documentation**: [Strands Agent SDK Docs](https://github.com/strands-agents/docs)\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes\n4. Add tests for new functionality\n5. Run tests and ensure they pass\n6. Commit your changes: `git commit -m 'Add amazing feature'`\n7. Push to your branch: `git push origin feature/amazing-feature`\n8. Open a Pull Request\n\n### Code Standards\n\n- Follow PEP 8 style guidelines\n- Add type hints for all functions\n- Write docstrings for public APIs\n- Include tests for new features\n- Update documentation as needed\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.\n\n---\n\n**Built with \u2764\ufe0f for the Strands Agent SDK community**",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Strands Agent SDK documentation search and project assistance",
"version": "0.2.5",
"project_urls": {
"Homepage": "https://github.com/robpaterson/strands-mcp-server",
"Issues": "https://github.com/robpaterson/strands-mcp-server/issues",
"Repository": "https://github.com/robpaterson/strands-mcp-server"
},
"split_keywords": [
"agents",
" documentation",
" llm",
" mcp",
" strands"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "26e9b756e965eee4cf266a1c19dfed038d6cfc2f418044df42f9d50960ed0c4a",
"md5": "30d4f9e97c7ac1df5bbf88f7284d1513",
"sha256": "1b29b080cd25784e38308cbb936a8811cfc4101f752753b55c4d2e39e3877153"
},
"downloads": -1,
"filename": "patersr_strands_mcp_server-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "30d4f9e97c7ac1df5bbf88f7284d1513",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 417312,
"upload_time": "2025-08-31T12:44:35",
"upload_time_iso_8601": "2025-08-31T12:44:35.252640Z",
"url": "https://files.pythonhosted.org/packages/26/e9/b756e965eee4cf266a1c19dfed038d6cfc2f418044df42f9d50960ed0c4a/patersr_strands_mcp_server-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "26efd3bc627e1f12dd5c18ccd2a8d71d854b1b2edb01864916e303886890f97a",
"md5": "4d96482b8173e2a838d3d775211f4ae9",
"sha256": "f893f2c7f2d1536a117ececcc52067a39390221805dcb347fa094b3d6d0cac59"
},
"downloads": -1,
"filename": "patersr_strands_mcp_server-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "4d96482b8173e2a838d3d775211f4ae9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 343978,
"upload_time": "2025-08-31T12:44:36",
"upload_time_iso_8601": "2025-08-31T12:44:36.804594Z",
"url": "https://files.pythonhosted.org/packages/26/ef/d3bc627e1f12dd5c18ccd2a8d71d854b1b2edb01864916e303886890f97a/patersr_strands_mcp_server-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 12:44:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "robpaterson",
"github_project": "strands-mcp-server",
"github_not_found": true,
"lcname": "patersr-strands-mcp-server"
}
JSON
