Metadata-Version: 2.5
Name: strands-agents-mcp-server
Version: 0.4.0
Summary: A Model Context Protocol server that provides knowledge about building AI agents with Strands Agents
Project-URL: Homepage, https://github.com/strands-agents/harness-sdk
Project-URL: Bug Tracker, https://github.com/strands-agents/harness-sdk/issues
Project-URL: Documentation, https://strandsagents.com
Author-email: AWS <opensource@amazon.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp<2.2,>=1.21.2
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: commitizen>=4.4.0; extra == 'dev'
Requires-Dist: hatch>=1.0.0; extra == 'dev'
Requires-Dist: packaging<27.0.0,>=23.0; extra == 'dev'
Requires-Dist: pre-commit>=2.20.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.0.0; extra == 'dev'
Requires-Dist: pytest>=9.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.4; extra == 'dev'
Requires-Dist: tomli<3.0.0,>=2.0.0; (python_version < '3.11') and extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">
  <div>
    <a href="https://strandsagents.com">
      <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://strandsagents.com/latest/assets/wordmark-github-dark.svg">
        <img src="https://strandsagents.com/latest/assets/wordmark-github-light.svg" alt="Strands" width="320">
      </picture>
    </a>
  </div>

  <h1>
    Strands Agents MCP Server
  </h1>

  <h2>
    A model-driven approach to building AI agents in just a few lines of code.
  </h2>

  <div align="center">
    <a href="https://github.com/strands-agents/harness-sdk/graphs/commit-activity"><img alt="GitHub commit activity" src="https://img.shields.io/github/commit-activity/m/strands-agents/harness-sdk"/></a>
    <a href="https://github.com/strands-agents/harness-sdk/issues"><img alt="GitHub open issues" src="https://img.shields.io/github/issues/strands-agents/harness-sdk"/></a>
    <a href="https://github.com/strands-agents/harness-sdk/pulls"><img alt="GitHub open pull requests" src="https://img.shields.io/github/issues-pr/strands-agents/harness-sdk"/></a>
    <a href="https://github.com/strands-agents/harness-sdk/blob/main/LICENSE.APACHE"><img alt="License" src="https://img.shields.io/github/license/strands-agents/harness-sdk"/></a>
    <a href="https://pypi.org/project/strands-agents-mcp-server/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/strands-agents-mcp-server"/></a>
    <a href="https://python.org"><img alt="Python versions" src="https://img.shields.io/pypi/pyversions/strands-agents-mcp-server"/></a>
    <a href="https://discord.gg/strands"><img alt="Strands Discord" src="https://img.shields.io/badge/Discord-Strands-5865F2?logo=discord&logoColor=white"/></a>
  </div>

  <p>
    <a href="https://strandsagents.com/">Documentation</a>
    ◆ <a href="https://github.com/strands-agents/samples">Samples</a>
    ◆ <a href="https://github.com/strands-agents/harness-sdk/tree/main/strands-cli">CLI</a>
    ◆ <a href="https://github.com/strands-agents/harness-sdk/tree/main/strands-mcp">MCP Server</a>
    <br>
    Harness (<a href="https://github.com/strands-agents/harness-sdk/tree/main/harness-py">Python</a>, <a href="https://github.com/strands-agents/harness-sdk/tree/main/harness-ts">TypeScript</a>)
    ◆ SDK (<a href="https://github.com/strands-agents/harness-sdk/tree/main/strands-py">Python</a>, <a href="https://github.com/strands-agents/harness-sdk/tree/main/strands-ts">TypeScript</a>)
    ◆ <a href="https://github.com/strands-agents/box">Box</a>
    ◆ <a href="https://github.com/strands-agents/shell">Shell</a>
    ◆ <a href="https://github.com/strands-agents/evals">Evals</a>
    ◆ <a href="https://github.com/strands-labs">Labs</a>
  </p>
</div>

This MCP server provides curated documentation access to your GenAI tools via llms.txt files, enabling AI coding assistants to find pages by title and retrieve their contents.

## Features

- **Document Search**: Field-weighted BM25 ranking over page titles, URL paths, and llms.txt descriptions, extended to page content once a page is hydrated (fetched), so body terms become searchable
- **Section-Based Browsing**: Browse document structure via table of contents, then fetch only the section you need - more token-efficient than retrieving full pages
- **Curated Content**: Indexes documentation from llms.txt files with clean, human-readable titles
- **On-Demand Fetching**: Lazy-loads full document content only when needed for optimal performance
- **Snippet Generation**: Hydrates the top-ranked pages to provide contextual previews
- **Real URL Support**: Works with actual HTTPS URLs while maintaining backward compatibility

### Tool behavior

- `search_docs(query, k, alternate_queries)` ranks by page title, URL path, and llms.txt description, and by page content once a page has been hydrated. Both title-like keywords and body terms work; call `fetch_doc` to inspect a result's contents. The changelog index, which concatenates every release note, is ranked by title and description only.
- `alternate_queries` takes up to 4 other phrasings of the same question. Each phrasing is searched and the rankings are combined with reciprocal rank fusion, so pages matched by several phrasings rank first. Phrasings that tokenize the same as an earlier one are searched once.
- Search scores are unbounded field-weighted BM25 values, or fused rank scores when `alternate_queries` are given. They are useful only for ordering results from the same query; they are not probabilities and should not be compared across queries.
- `search_docs` returns an empty list when no document matches. If a matched page cannot be fetched for its snippet, the result still includes the URL and title.
- `fetch_doc` returns `{"error": "...", "url": "...", "hint": "..."}` for unsupported URLs, URLs that are not in
  the docs catalog (with the closest catalog URLs as `suggestions`), and unknown section IDs (with the valid
  `sections`); `section` is ignored when the full document is returned automatically. A catalog page that cannot be
  fetched is reported as a tool error (`isError: true`).
- `find_integrations(query, type, language, maintained_by, sdk, limit)` filters the integrations catalog feed at
  `https://strandsagents.com/integrations.json`, fetched on first use and cached for 10 minutes. It returns the total
  match count and up to `limit` results carrying the maintainer, install commands, and a docs URL; on-site docs URLs
  can be passed to `fetch_doc`. A failed refresh keeps serving the cached copy; a feed that has never loaded is
  reported as a tool error.
- All tools are annotated read-only and idempotent, and the server sends `instructions` telling clients when to use
  it and in which order to call the tools.

## Configuration

- `STRANDS_MCP_PREFETCH_ALL`: when set to a truthy value (`1`, `true`, `yes`), the server prefetches and indexes all pages in the background at startup, so body-term search works immediately instead of only after a page has been hydrated by a prior query. Defaults to off. Prefetch is best-effort and eventually consistent: results may be title-only until background hydration completes.

## Prerequisites

The usage methods below require [uv](https://github.com/astral-sh/uv) to be installed on your system. You can install it by following the [official installation instructions](https://github.com/astral-sh/uv#installation).

## Installation

You can use the Strands Agents MCP server with
[40+ applications that support MCP servers](https://modelcontextprotocol.io/clients),
including Amazon Q Developer CLI, Anthropic Claude Code, Cline, and Cursor.

Get started quickly with one-click installation buttons for popular MCP clients. Click the buttons below to install servers directly in your IDE:

[![Install in Kiro](https://img.shields.io/badge/Install-Kiro-9046FF?style=for-the-badge&logo=kiro)](https://kiro.dev/launch/mcp/add?name=strands-agents&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22strands-agents-mcp-server%22%5D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%22search_docs%22%2C%22fetch_doc%22%5D%7D)
[![Install in Cursor](https://img.shields.io/badge/Install-Cursor-blue?style=for-the-badge&logo=cursor)](https://cursor.com/en-US/install-mcp?name=strands-agents&config=eyJjb21tYW5kIjoidXZ4IHN0cmFuZHMtYWdlbnRzLW1jcC1zZXJ2ZXIifQ%3D%3D)
[![Install in VS Code](https://img.shields.io/badge/Install-VS_Code-FF9900?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22strands-agents%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22strands-agents-mcp-server%22%5D%7D)

### Kiro example

See the [Kiro documentation](https://kiro.dev/docs/mcp/configuration/)
for instructions on managing MCP configuration.

In `~/.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "strands-agents": {
      "command": "uvx",
      "args": ["strands-agents-mcp-server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": ["search_docs", "fetch_doc"]
    }
  }
}
```

### Q Developer CLI example

See the [Q Developer CLI documentation](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/command-line-mcp-configuration.html)
for instructions on managing MCP configuration.

In `~/.aws/amazonq/mcp.json`:

```json
{
  "mcpServers": {
    "strands-agents": {
      "command": "uvx",
      "args": ["strands-agents-mcp-server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": ["search_docs", "fetch_doc"]
    }
  }
}
```

### Claude Code example

See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/tutorials#configure-mcp-servers)
for instructions on managing MCP servers.

```bash
claude mcp add strands uvx strands-agents-mcp-server
```

### Cline example

See the [Cline documentation](https://docs.cline.bot/mcp-servers/configuring-mcp-servers#editing-mcp-settings-files)
for instructions on managing MCP configuration.

Provide Cline with the following information:

```
I want to add the MCP server for Strands Agents.
Here's the GitHub link: @https://github.com/strands-agents/harness-sdk/tree/main/strands-mcp
Can you add it?"
```

### Cursor example

See the [Cursor documentation](https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers)
for instructions on managing MCP configuration.

In `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "strands-agents": {
      "command": "uvx",
      "args": ["strands-agents-mcp-server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "INFO"
      },
      "disabled": false,
      "autoApprove": ["search_docs", "fetch_doc"]
    }
  }
}
```

### VS Code example

See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)
for instructions on managing MCP configuration.

In your `mcp.json` file:

```json
{
  "servers": {
    "strands-agents": {
      "command": "uvx",
      "args": ["strands-agents-mcp-server"]
    }
  }
}
```

## Quick Testing

You can quickly test the MCP server using the MCP Inspector:

```bash
# For published package
npx @modelcontextprotocol/inspector uvx strands-agents-mcp-server

# For local development
npx @modelcontextprotocol/inspector python -m strands_mcp_server
```

Note: This requires [npx](https://docs.npmjs.com/cli/v11/commands/npx) to be installed on your system. It comes bundled with [Node.js](https://nodejs.org/).

The Inspector is also useful for troubleshooting MCP server issues as it provides detailed connection and protocol information. For an in-depth guide, have a look at the [MCP Inspector documentation](https://modelcontextprotocol.io/docs/tools/inspector).

## Getting Started

1. **Install prerequisites**:

   - Install [uv](https://github.com/astral-sh/uv) following the [official installation instructions](https://github.com/astral-sh/uv#installation)
   - Make sure you have [Node.js](https://nodejs.org/) installed for npx commands

2. **Configure your MCP client**:

   - Choose your preferred MCP client from the installation examples above
   - Add the Strands Agents MCP server configuration to your client

3. **Test the connection**:

   ```bash
   # For published package
   npx @modelcontextprotocol/inspector uvx strands-agents-mcp-server

   # For local development
   npx @modelcontextprotocol/inspector python -m strands_mcp_server
   ```

4. **Start using the documentation tools**:
   - `search_docs` - Find relevant documentation with intelligent ranking
   - `fetch_doc` - Browse a page's structure and preamble, then read individual sections
   - `find_integrations` - Filter the integrations catalog by type, language, and maintainer
   - The server automatically indexes curated content from llms.txt files

## Server Development

```bash
git clone https://github.com/strands-agents/harness-sdk.git
cd harness-sdk/strands-mcp
python3 -m venv venv
source venv/bin/activate
pip3 install -e ".[dev]"

npx @modelcontextprotocol/inspector python -m strands_mcp_server
```

### Running Tests

```bash
# Unit tests (fast, no network access required)
pytest tests/

# Integration tests (requires network access to strandsagents.com)
pytest tests_integ/ -v

# All tests
pytest tests/ tests_integ/ -v
```

To skip integration tests (e.g., in CI environments without network access):

```bash
SKIP_INTEG_TESTS=1 pytest tests_integ/
```

## Contributing ❤️

We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details on:

- Reporting bugs & features
- Development setup
- Contributing via Pull Requests
- Code of Conduct
- Reporting of security issues

## Stay in touch with the team
Come meet the Strands team and other users on [**Discord**](https://discord.com/invite/strands)

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## Security

See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.
