### Manual Installation

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/README.md

Manual installation using pip.

```bash
pip install mcp-simple-pubmed
```

--------------------------------

### FullTextClient Direct Use Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/configuration.md

Python code example for initializing FullTextClient directly.

```python
from mcp_simple_pubmed.fulltext_client import FullTextClient

client = FullTextClient(
    email="research@example.com",        # Required
    tool="my-tool-name",                # Required
    api_key="optional-api-key"          # Optional
)
```

--------------------------------

### PubMedClient Direct Use Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/configuration.md

Python code example for initializing PubMedClient directly.

```python
from mcp_simple_pubmed.pubmed_client import PubMedClient

client = PubMedClient(
    email="research@example.com",        # Required
    tool="my-tool-name",                # Required
    api_key="optional-api-key"          # Optional
)
```

--------------------------------

### PICO Search Example Usage

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Example of how to use the pico_search function to get a prompt for a PICO-based PubMed query.

```python
prompt = await client.get_prompt(
    "pico_search",
    arguments={
        "population": "adults with type 2 diabetes",
        "intervention": "metformin",
        "comparison": "placebo",
        "outcome": "HbA1c reduction"
    }
)
```

--------------------------------

### PUBMED_API_KEY Environment Variable Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/configuration.md

Example of how to set both PUBMED_EMAIL and PUBMED_API_KEY environment variables.

```bash
export PUBMED_EMAIL="research@example.com"
export PUBMED_API_KEY="your-ncbi-api-key-here"
```

--------------------------------

### PUBMED_EMAIL Environment Variable Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/configuration.md

Example of how to set the PUBMED_EMAIL environment variable.

```bash
export PUBMED_EMAIL="research@example.com"
```

--------------------------------

### check_full_text_availability Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/fulltext-client.md

Example usage for checking full text availability.

```python
# Check if full text is available
available, pmc_id = await client.check_full_text_availability("39661433")
if available:
    print(f"Full text available in PMC: {pmc_id}")
else:
    print("Full text not available in PubMed Central")
```

--------------------------------

### Example URLs Object

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

An example of the URLs object structure.

```python
{
    "pubmed": "https://pubmed.ncbi.nlm.nih.gov/39661433/",
    "pubmed_mobile": "https://m.pubmed.ncbi.nlm.nih.gov/39661433/",
    "doi": "https://doi.org/10.1038/s41591-024-01234-5",
    "pmc": "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC9876543/"
}
```

--------------------------------

### PUBMED_TOOL Environment Variable Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/configuration.md

Example of how to set PUBMED_EMAIL and PUBMED_TOOL environment variables.

```bash
export PUBMED_EMAIL="research@example.com"
export PUBMED_TOOL="my-research-assistant"
```

--------------------------------

### Systematic Review Search Example Usage

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Example of how to use the systematic_review_search function to get a prompt for a PubMed search strategy.

```python
prompt = await client.get_prompt(
    "systematic_review_search",
    arguments={"topic": "diabetes prevention", "years": "3"}
)
```

--------------------------------

### Article Metadata Object Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

An example of the Article Metadata Object.

```python
{
    "pmid": "39661433",
    "title": "Deep Learning Applications in Medical Imaging",
    "abstract": "This review examines the application of deep learning...",
    "journal": "Nature Medicine",
    "authors": ["Smith John", "Johnson Jane", "Williams Robert"],
    "publication_date": {
        "year": "2024",
        "month": "01",
        "day": "15"
    },
    "keywords": ["machine learning", "neural networks", "image analysis"],
    "mesh_terms": [
        {
            "descriptor": "Deep Learning",
            "ui": "D000069452",
            "qualifiers": [
                {"name": "methods", "ui": "Q000379"}
            ]
        }
    ],
    "doi": "10.1038/s41591-024-01234-5",
    "pmcid": "PMC9876543"
}
```

--------------------------------

### Author Search Example Usage

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Example of how to use the author_search function to get a prompt for searching PubMed by author.

```python
prompt = await client.get_prompt(
    "author_search",
    arguments={"author_name": "Fauci Anthony", "affiliation": "NIH"}
)
```

--------------------------------

### get_full_text Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/fulltext-client.md

Example usage for retrieving full text with and without a PMC ID.

```python
# Get full text with automatic PMC ID lookup
full_text = await client.get_full_text("39661433")
if full_text:
    print("Full text retrieved (XML format)")
else:
    print("Full text not available")

# Get full text with known PMC ID (skips lookup)
full_text = await client.get_full_text("39661433", pmc_id="9876543")
```

--------------------------------

### PubMedSearch Client Initialization

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/configuration.md

Example of how to initialize the PubMedSearch client with required and optional parameters.

```python
from mcp_simple_pubmed.pubmed_search import PubMedSearch

client = PubMedSearch(
    email="research@example.com",        # Required (raises ValueError if missing)
    tool="my-tool-name",                # Required
    api_key="optional-api-key"          # Optional
)
```

--------------------------------

### Windows Claude Desktop Configuration Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/configuration.md

JSON configuration for launching the simple-pubmed server via Claude Desktop on Windows.

```json
{
  "mcpServers": {
    "simple-pubmed": {
      "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python311\\python.exe",
      "args": ["-m", "mcp_simple_pubmed"],
      "env": {
        "PUBMED_EMAIL": "your-email@example.com",
        "PUBMED_API_KEY": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### macOS Claude Desktop Configuration Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/configuration.md

JSON configuration for launching the simple-pubmed server via Claude Desktop on macOS.

```json
{
  "mcpServers": {
    "simple-pubmed": {
      "command": "python",
      "args": ["-m", "mcp_simple_pubmed"],
      "env": {
        "PUBMED_EMAIL": "your-email@example.com",
        "PUBMED_API_KEY": "your-api-key"
      }
    }
  }
}
```

--------------------------------

### PubMedSearch Initialization Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-search.md

Example usage of initializing the PubMedSearch client.

```python
from mcp_simple_pubmed.pubmed_search import PubMedSearch

client = PubMedSearch(
    email="research@example.com",
    tool="my-research-tool",
    api_key="your-ncbi-api-key"  # Optional
)
```

--------------------------------

### Install via Smithery

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/README.md

To install Simple PubMed for Claude Desktop automatically via Smithery.

```bash
npx -y @smithery/cli install mcp-simple-pubmed --client claude
```

--------------------------------

### Publication Date Object Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

An example of a Publication Date Object.

```python
{
    "year": "2024",
    "month": "01",
    "day": "15"
}
```

--------------------------------

### Install Certificates Command

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/README.md

Command to run the Python SSL certificate installation script on macOS. Replace '3.13' with your specific Python version.

```bash
/Applications/Python\ 3.13/Install\ Certificates.command
```

--------------------------------

### MeSH Term Object Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

An example of a MeSH Term Object with qualifiers.

```python
{
    "descriptor": "Breast Neoplasms",
    "ui": "D001943",
    "qualifiers": [
        {"name": "genetics", "ui": "Q000235"},
        {"name": "therapy", "ui": "Q000628"}
    ]
}
```

--------------------------------

### _clean_text Example Usage

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

Example demonstrating the _clean_text method for normalizing whitespace and handling None input.

```python
client = PubMedFetch()

text = "This   has\n\nmultiple    spaces"
cleaned = client._clean_text(text)
# Result: "This has multiple spaces"

# None passthrough
result = client._clean_text(None)
# Result: None
```

--------------------------------

### Resource Handler Example Usage

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Demonstrates how to read the abstract and full text of a PubMed article using the resource handler.

```python
# Read abstract
abstract = await client.read_resource("pubmed://39661433/abstract")
```

```python
# Read full text
fulltext = await client.read_resource("pubmed://39661433/full_text")
```

--------------------------------

### Example Output of _generate_urls

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-search.md

Example dictionary output from the _generate_urls function, showing various article URLs.

```python
{
    "pubmed": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
    "pubmed_mobile": "https://m.pubmed.ncbi.nlm.nih.gov/12345678/",
    "doi": "https://doi.org/10.1234/example",
    "pmc": "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC9876543/"
}
```

--------------------------------

### Example Search Results with Resources

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

An example of the search results object structure when returned by the search_pubmed tool.

```python
{
    "pmid": "39661433",
    "title": "Deep Learning Applications in Medical Imaging",
    "abstract": "This review examines the application of deep learning...",
    # ... other fields ...
    "abstract_uri": "pubmed://39661433/abstract",
    "full_text_uri": "pubmed://39661433/full_text",
    "pubmed_url": "https://pubmed.ncbi.nlm.nih.gov/39661433/",
    "pmc_url": "https://www.ncbi.nlm.nih.gov/pmc/articles/PMC9876543/",
    "doi_url": "https://doi.org/10.1038/s41591-024-01234-5"
}
```

--------------------------------

### Using the MCP Server (via Claude)

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/API-INDEX.md

Examples of interacting with the mcp-simple-pubmed server using tools like Claude.

```python
# Search for articles
result = await client.call_tool(
    "search_pubmed",
    {"query": "covid vaccine", "max_results": 5}
)

# Get full text
result = await client.call_tool(
    "get_paper_fulltext",
    {"pmid": "39661433"}
)

# Read abstract via resource
abstract = await client.read_resource("pubmed://39661433/abstract")
```

--------------------------------

### Using PubMedClient directly

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/API-INDEX.md

Examples of using the PubMedClient class from the Python library.

```python
from mcp_simple_pubmed.pubmed_client import PubMedClient

client = PubMedClient(
    email="test@example.com",
    tool="my-tool",
    api_key="optional-key"
)

# Search
articles = await client.search_articles("diabetes treatment", max_results=10)

# Get specific article
article = await client.get_article_details("39661433")
print(article["title"])
```

--------------------------------

### Basic Usage Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

Demonstrates the basic usage pattern of the PubMedFetch class, including fetching full text and checking the result.

```python
from mcp_simple_pubmed.pubmed_fetch import PubMedFetch
import asyncio

async def main():
    fetch = PubMedFetch()
    
    # Get full text for an article
    text = await fetch.get_full_text("24677277")
    
    # Process the text
    if "MAIN TEXT" in text:
        print("Successfully retrieved full text")
    elif "DOI" in text:
        print("Article has DOI for alternate access")
    else:
        print("Full text not available")

asyncio.run(main())
```

--------------------------------

### Error Handling Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

An example of how to fetch article text with fallback mechanisms for unavailable articles or DOI extraction.

```python
async def fetch_with_fallback(pmid: str) -> str:
    from mcp_simple_pubmed.pubmed_fetch import PubMedFetch
    
    fetch = PubMedFetch()
    result = await fetch.get_full_text(pmid)
    
    # Check if successful by looking for content markers
    if "MAIN TEXT" in result:
        return result  # Success
    elif "DOI" in result:
        # Try accessing via DOI
        return extract_doi_from_message(result)
    else:
        # Not available
        return f"Article {pmid} not available in PMC"

```

--------------------------------

### get_paper_fulltext Example Usage

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Shows how to fetch the full text of an article using its PMID.

```python
# Fetch full text by PMID
result = await client.call_tool(
    "get_paper_fulltext",
    {"pmid": "39661433"}
)
print(result.data)  # Full text or "not available" message
```

--------------------------------

### Basic search_articles Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-search.md

Example of a basic search using the search_articles method.

```python
# Basic search
articles = await client.search_articles("tuberculosis treatment", max_results=5)
for article in articles:
    print(article["title"])
    print(article["urls"]["pubmed"])
```

--------------------------------

### search_articles Example with Date Range

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-search.md

Example of using search_articles with a specific date range.

```python
# Search with date range
articles = await client.search_articles(
    '"heart disease"[Title] AND 2020:2024[PDAT]',
    max_results=10
)
```

--------------------------------

### Accessing Article URLs Example

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-search.md

Example demonstrating how to access article URLs returned by search_articles.

```python
# Access article URLs
for article in articles:
    print(f"Title: {article['title']}")
    print(f"PubMed: {article['urls']['pubmed']}")
    if "doi" in article["urls"]:
        print(f"DOI: {article['urls']['doi']}")
```

--------------------------------

### _extract_text_from_pmc_xml Example Usage

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

Example of how to use the _extract_text_from_pmc_xml method to extract text from an XML content, including error handling.

```python
import xml.etree.ElementTree as ET

client = PubMedFetch()

# Assuming xml_content is bytes from Entrez.efetch()
with open("pmc_article.xml", "rb") as f:
    xml_content = f.read()

try:
    text = client._extract_text_from_pmc_xml(xml_content)
    print(text)
except ValueError as e:
    print(f"Error extracting text: {e}")
```

--------------------------------

### get_full_text Example Usage

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

Example of how to use the get_full_text method to fetch and print the full text of a PubMed article.

```python
from mcp_simple_pubmed.pubmed_fetch import PubMedFetch

client = PubMedFetch()

# Fetch full text
result = await client.get_full_text("24677277")
print(result)

# Output format:
# "Title of Article
#  
#  ABSTRACT
#  Abstract text content...
#  
#  MAIN TEXT
#  Section Title
#  Paragraph content...
#  
#  Introduction
#  Introduction text..."
```

--------------------------------

### Example Handling of PmidMismatchError

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Demonstrates how to catch and handle PmidMismatchError, printing the requested and found PMIDs.

```python
from mcp_simple_pubmed.fulltext_client import FullTextClient, PmidMismatchError

client = FullTextClient(email="test@example.com", tool="my-tool")

try:
    full_text = await client.get_full_text("36738762")
except PmidMismatchError as e:
    print(f"Requested PMID: {e.requested_pmid}")
    print(f"Found PMID: {e.found_pmid}")
    print("Article mismatch — may not be open access in PMC")
```

--------------------------------

### Example of Invalid Resource Type ValueError

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Illustrates accessing a resource with an invalid resource type, triggering a ValueError.

```python
# Invalid resource type
result = await client.read_resource("pubmed://39661433/wrong_type")
# ValueError: Invalid resource type requested: wrong_type
```

--------------------------------

### Example Usage: Handling PMID Mismatch

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/fulltext-client.md

Demonstrates how to use the FullTextClient and catch a PmidMismatchError, printing the requested and found PMIDs.

```python
from mcp_simple_pubmed.fulltext_client import PmidMismatchError

try:
    full_text = await client.get_full_text("36738762")
except PmidMismatchError as e:
    print(f"Requested PMID: {e.requested_pmid}")
    print(f"Found PMID: {e.found_pmid}")
    print(f"Articles do not match - article may not be open access in PMC")
```

--------------------------------

### FullTextClient Usage

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/API-INDEX.md

Example demonstrating how to use the FullTextClient to check full-text availability and retrieve the full text of a PubMed article.

```python
from mcp_simple_pubmed.fulltext_client import FullTextClient, PmidMismatchError

client = FullTextClient(
    email="test@example.com",
    tool="my-tool"
)

try:
    # Check availability
    available, pmc_id = await client.check_full_text_availability("39661433")
    
    if available:
        # Get full text
        full_text = await client.get_full_text("39661433", pmc_id=pmc_id)
        print(full_text[:500])  # First 500 chars of XML
except PmidMismatchError as e:
    print(f"Article mismatch: {e.requested_pmid} vs {e.found_pmid}")
```

--------------------------------

### Example of Error in Search Request (MCP Tool) ValueError

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Shows an example of a malformed search query that causes a ValueError when processing the search request.

```python
# Malformed query that causes XML parsing error
result = await client.call_tool("search_pubmed", {"query": "<<<invalid>>", "max_results": 10})
# ValueError: Error processing search request: ...
```

--------------------------------

### Example of Email Required (PubMedSearch) ValueError

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Demonstrates instantiating PubMedSearch with an empty email, which raises a ValueError.

```python
from mcp_simple_pubmed.pubmed_search import PubMedSearch

# This will raise ValueError
client = PubMedSearch(email="", tool="my-tool")
# ValueError: Email is required for PubMed search
```

--------------------------------

### search_pubmed Example Usage

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Demonstrates various ways to use the search_pubmed tool, including basic keyword search, field-specific search, and author search.

```python
# Basic keyword search
result = await client.call_tool(
    "search_pubmed",
    {"query": "covid vaccine", "max_results": 5}
)
```

```python
# Field-specific search with date range
result = await client.call_tool(
    "search_pubmed",
    {"query": "breast cancer[Title] AND 2023[Date - Publication]", "max_results": 10}
)
```

```python
# Author search
result = await client.call_tool(
    "search_pubmed",
    {"query": "Smith J[Author] AND diabetes", "max_results": 20}
)
```

--------------------------------

### Example Log Entries

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Illustrative log messages showing different severity levels (INFO, ERROR, WARNING) related to PubMed operations.

```text
INFO:pubmed-client:Searching PubMed with query: covid vaccine
INFO:pubmed-client:Found 47 articles
ERROR:pubmed-client:Error getting article details for PMID 12345: ...
WARNING:pubmed-fulltext:PMID mismatch for 36738762: requested 36738762, found 12345678 in PMC
```

--------------------------------

### Example of PUBMED_EMAIL Not Set ValueError

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Illustrates the scenario where the PUBMED_EMAIL environment variable is not set, leading to a ValueError.

```python
import os
# PUBMED_EMAIL not set
from mcp_simple_pubmed import server

# ValueError: PUBMED_EMAIL environment variable is required
```

--------------------------------

### Get Article Details

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-client.md

Fetches complete metadata for a specific article by its PubMed ID (PMID).

```python
# Fetch specific article
article = await client.get_article_details("39661433")
if article:
    print(f"Title: {article['title']}")
    print(f"Authors: {', '.join(article['authors'])}")
    print(f"MeSH Terms: {len(article['mesh_terms'])}")
else:
    print("Article not found")
```

--------------------------------

### Example: Invalid Resource URL

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Illustrates a ValueError that can occur when attempting to read a resource with an invalid PubMed identifier.

```python
result = await client.read_resource("pubmed://invalid_pmid/abstract")
# ValueError: Error reading resource: ...
```

--------------------------------

### Safe Search and Fetch Full Text

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Example functions demonstrating safe usage of PubMedClient and FullTextClient, including handling potential exceptions like PmidMismatchError.

```python
from mcp_simple_pubmed.pubmed_client import PubMedClient
from mcp_simple_pubmed.fulltext_client import FullTextClient, PmidMismatchError

async def safe_search():
    try:
        client = PubMedClient(email="test@example.com", tool="my-tool")
        results = await client.search_articles("cancer", max_results=10)
        return results
    except Exception as e:
        logger.error(f"Search failed: {e}")
        return []

async def safe_fetch_fulltext(pmid):
    try:
        client = FullTextClient(email="test@example.com", tool="my-tool")
        full_text = await client.get_full_text(pmid)
        return full_text
    except PmidMismatchError as e:
        print(f"Article {e.requested_pmid} is not open access in PMC")
        return None
    except Exception as e:
        logger.error(f"Failed to fetch full text: {e}")
        return None
```

--------------------------------

### Example: Invalid PMID for Full Text Retrieval

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Demonstrates how an invalid PMID might trigger a ValueError when calling the get_paper_fulltext tool.

```python
# Invalid PMID
result = await client.call_tool("get_paper_fulltext", {"pmid": "invalid"})
# May return: ValueError: Error retrieving full text: ...
```

--------------------------------

### Command Line Entry Point

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/API-INDEX.md

How to run the mcp-simple-pubmed package from the command line.

```bash
python -m mcp_simple_pubmed
```

--------------------------------

### Main Entry Point Function Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Runs the MCP server.

```python
def main()
```

--------------------------------

### FullTextClient Constructor

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/fulltext-client.md

Initializes the full text client with required NCBI Entrez API credentials.

```python
from mcp_simple_pubmed.fulltext_client import FullTextClient

client = FullTextClient(
    email="research@example.com",
    tool="my-research-tool",
    api_key="your-ncbi-api-key"  # Optional
)
```

--------------------------------

### Logging Configuration

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/configuration.md

Standard Python logging configuration for the project modules.

```python
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("pubmed-server")  # or other module names
```

--------------------------------

### Constructor Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/fulltext-client.md

The constructor for the FullTextClient class.

```python
def __init__(self, requested_pmid: str, found_pmid: str)
```

--------------------------------

### Server Initialization

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Initializes the MCP server using the FastMCP framework.

```python
from fastmcp import FastMCP
app = FastMCP("pubmed-server")
```

--------------------------------

### Python Import Entry Points

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/API-INDEX.md

How to import the main clients from the mcp-simple-pubmed Python package.

```python
from mcp_simple_pubmed.pubmed_client import PubMedClient
from mcp_simple_pubmed.fulltext_client import FullTextClient
```

--------------------------------

### PubMedClient Constructor

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-client.md

Initializes the PubMed client with required credentials for NCBI Entrez API access.

```python
from mcp_simple_pubmed.pubmed_client import PubMedClient

client = PubMedClient(
    email="research@example.com",
    tool="my-research-tool",
    api_key="your-ncbi-api-key"  # Optional
)
```

--------------------------------

### Claude Desktop Configuration (Windows)

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/README.md

Add to your Claude Desktop configuration for Windows.

```json
{
  "mcpServers": {
    "simple-pubmed": {
      "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Local\\Programs\\Python\\Python311\\python.exe",
      "args": [
        "-m",
        "mcp_simple_pubmed"
      ],
      "env": {
        "PUBMED_EMAIL": "your-email@example.com",
        "PUBMED_API_KEY": "your-api-key" 
      }
    }
  }
}
```

--------------------------------

### PubMedSearch Constructor

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-search.md

Initializes the PubMed search client with required NCBI credentials.

```python
def __init__(self, email: str, tool: str, api_key: Optional[str] = None)
```

--------------------------------

### configure_clients Function Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-client.md

Signature for the configure_clients function, which initializes PubMedClient.

```python
def configure_clients() -> Tuple[PubMedClient, FullTextClient]
```

--------------------------------

### PICO Search Function Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Builds a PICO-based (Population, Intervention, Comparison, Outcome) search query for clinical questions.

```python
def pico_search(
    population: str,
    intervention: str,
    comparison: str = "",
    outcome: str = ""
) -> List[TextContent]
```

--------------------------------

### Module Structure

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/API-INDEX.md

The directory structure of the mcp-simple-pubmed Python package.

```bash
mcp_simple_pubmed/
├── __init__.py           # Package initialization, main() entry point
├── __main__.py          # CLI entry point
├── server.py            # MCP server with tools, resources, prompts
├── pubmed_client.py     # PubMedClient class
├── fulltext_client.py   # FullTextClient class, PmidMismatchError
├── pubmed_search.py     # PubMedSearch class
└── pubmed_fetch.py      # PubMedFetch class
```

--------------------------------

### Claude Desktop Configuration (Mac OS)

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/README.md

Add to your Claude Desktop configuration for Mac OS.

```json
{
  "mcpServers": {
    "simple-pubmed": {
      "command": "python",
      "args": ["-m", "mcp_simple_pubmed"],
      "env": {
        "PUBMED_EMAIL": "your-email@example.com",
        "PUBMED_API_KEY": "your-api-key" 
      }
    }
  }
}
```

--------------------------------

### Search Results with Resources (MCP Server)

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

When returned by the search_pubmed tool, articles include additional resource URIs for MCP integration.

```python
{
    # ... all Article Metadata Object fields ...
    "abstract_uri": str,            # MCP resource URI: pubmed://{pmid}/abstract
    "full_text_uri": str,           # MCP resource URI: pubmed://{pmid}/full_text
    "doi_url": Optional[str],       # Direct URL to DOI (if doi exists)
    "pubmed_url": str,              # Direct PubMed URL
    "pmc_url": Optional[str]        # Direct PMC URL (if pmcid exists)
}
```

--------------------------------

### Configuration Validation

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

A Python function to validate environment variables for PubMed API configuration, including email and optional API key and tool name.

```python
import os

def validate_config():
    email = os.environ.get("PUBMED_EMAIL")
    if not email:
        raise ValueError("PUBMED_EMAIL must be set")
    
    # Optional: Validate email format
    if "@" not in email:
        raise ValueError("PUBMED_EMAIL must be a valid email address")
    
    return {
        "email": email,
        "api_key": os.environ.get("PUBMED_API_KEY"),
        "tool": os.environ.get("PUBMED_TOOL", "mcp-simple-pubmed")
    }
```

--------------------------------

### Search Articles - Basic

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-client.md

Performs a basic search for articles matching a query and retrieves their metadata.

```python
# Basic search
articles = await client.search_articles("tuberculosis treatment", max_results=5)
for article in articles:
    print(article["title"])
    print(article["pmid"])
```

--------------------------------

### Author Search Function Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Generates a prompt to find all publications by a specific author.

```python
def author_search(author_name: str, affiliation: str = "") -> List[TextContent]
```

--------------------------------

### Resolution for Email Required (PubMedSearch)

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Shows how to provide a valid email address when instantiating PubMedSearch.

```python
client = PubMedSearch(email="valid@example.com", tool="my-tool")
```

--------------------------------

### Systematic Review Search Function Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Generates a systematic review search strategy for a medical topic.

```python
def systematic_review_search(topic: str, years: str = "5") -> List[TextContent]
```

--------------------------------

### Formatted Text Output Structure

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

The expected structure of the formatted output from the _extract_text_from_pmc_xml() method.

```text
ARTICLE TITLE

ABSTRACT
Abstract text with multiple paragraphs joined.

MAIN TEXT

Section Title
Section content with paragraphs.

Another Section
More section content.

```

--------------------------------

### Article Metadata Object Structure

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/API-INDEX.md

The primary data structure for article metadata returned by the API.

```python
{
    "pmid": str,
    "title": str,
    "abstract": str,
    "journal": str,
    "authors": List[str],
    "publication_date": dict,
    "keywords": List[str],
    "mesh_terms": List[dict],
    "doi": Optional[str],
    "pmcid": Optional[str]
}
```

--------------------------------

### Resource Handler Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Defines the resource handler for reading different types of content for a given PubMed ID.

```python
@app.resource("pubmed://{pmid}/{resource_type}")
async def read_pubmed_resource(pmid: str, resource_type: str) -> str
```

--------------------------------

### Article Metadata Object Structure

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

The primary data structure returned by search and fetch operations. This is a Python dictionary with the specified structure.

```python
{
    "pmid": str,                    # PubMed ID (always present)
    "title": str,                   # Article title (may be "No title")
    "abstract": str,                # Abstract text (may be "No abstract available")
    "journal": str,                 # Journal name (empty string if not available)
    "authors": List[str],           # List of author full names
    "publication_date": {
        "year": Optional[str],
        "month": Optional[str],
        "day": Optional[str]
    },
    "keywords": List[str],          # Keywords extracted from article (optional)
    "mesh_terms": List[Dict],       # MeSH terms with qualifiers (optional)
    "doi": Optional[str],           # Digital Object Identifier (optional)
    "pmcid": Optional[str],         # PubMed Central ID (optional)
    "pmc_id": Optional[str],        # Alternative key for PMC ID (in some modules)
}
```

--------------------------------

### Qualifier Object Structure

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

Structure for a qualifier object within a MeSH Term.

```python
{
    "name": str,                    # Qualifier name (e.g., "genetics", "epidemiology")
    "ui": str                       # Qualifier unique identifier
}
```

--------------------------------

### _get_full_abstract Function Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-client.md

Signature for the _get_full_abstract function, which extracts complete abstract text.

```python
def _get_full_abstract(self, article_root: Optional[ET.Element]) -> Optional[str]
```

--------------------------------

### URLs Object (PubMedSearch)

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

Dictionary of human-accessible URLs for an article, as returned by the PubMedSearch class.

```python
{
    "pubmed": str,                  # Standard PubMed URL (always present)
    "pubmed_mobile": str,           # Mobile PubMed URL (always present)
    "doi": Optional[str],           # DOI URL (present if DOI available)
    "pmc": Optional[str]            # PMC URL (present if PMC ID available)
}
```

--------------------------------

### Resolution for PUBMED_EMAIL Not Set

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Shows how to set the PUBMED_EMAIL environment variable to resolve the ValueError.

```bash
export PUBMED_EMAIL="your-email@example.com"
python -m mcp_simple_pubmed
```

--------------------------------

### Publication Date Object Structure

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

Represents the publication date of an article with optional granularity.

```python
{
    "year": Optional[str],          # Four-digit year (may be null)
    "month": Optional[str],         # 1-2 digit month (may be null)
    "day": Optional[str]            # 1-2 digit day (may be null)
}
```

--------------------------------

### _clean_text Method Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

Signature for the _clean_text method, which normalizes whitespace in text content.

```python
def _clean_text(self, text: Optional[str]) -> Optional[str]
```

--------------------------------

### _extract_text_from_pmc_xml Method Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

Signature for the _extract_text_from_pmc_xml method, which extracts human-readable text content from a PubMed Central XML document.

```python
def _extract_text_from_pmc_xml(self, xml_content: bytes) -> str
```

--------------------------------

### PubMed Central XML Structure

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

Assumed standard PubMed Central article XML structure for the _extract_text_from_pmc_xml() method.

```xml
<article>
  <front>
    <article-meta>
      <title-group>
        <article-title>Title of Article</article-title>
      </title-group>
    </article-meta>
  </front>
  <body>
    <sec>
      <title>Section Title</title>
      <p>Paragraph text...</p>
    </sec>
  </body>
  <back>
    <abstract>
      <p>Abstract text...</p>
    </abstract>
  </back>
</article>

```

--------------------------------

### get_paper_fulltext Tool Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Defines the signature for the get_paper_fulltext tool, which retrieves the full text of a PubMed article.

```python
async def get_paper_fulltext(pmid: str) -> str
```

--------------------------------

### get_full_text Method Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

Signature for the get_full_text method, which retrieves the full text of an article by PMID.

```python
async def get_full_text(self, pmid: str) -> str
```

--------------------------------

### Type Aliases

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

Type aliases defined for clarity in the mcp-simple-pubmed package.

```python
# Dictionary of article metadata
ArticleMetadata = Dict[str, Any]

# List of articles
ArticleList = List[Dict[str, Any]]

# Tuple for availability check
AvailabilityTuple = Tuple[bool, Optional[str]]  # (is_available, pmc_id)
```

--------------------------------

### _get_xml_text Helper Method Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-search.md

Helper method to safely retrieve text from an XML element.

```python
def _get_xml_text(self, elem: Optional[ET.Element], xpath: str) -> Optional[str]
```

--------------------------------

### search_pubmed Tool Signature

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/server.md

Defines the signature for the search_pubmed tool, which searches PubMed.

```python
async def search_pubmed(query: str, max_results: int = 10) -> str
```

--------------------------------

### PmidMismatchError Class Definition

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/errors.md

Definition of the custom PmidMismatchError class, which inherits from Exception.

```python
class PmidMismatchError(Exception):
    """Raised when the PMC article's PMID does not match the requested PMID."""
```

--------------------------------

### MeSH Term Object Structure

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/types.md

Structure for Medical Subject Heading terms with qualifiers.

```python
{
    "descriptor": str,              # MeSH descriptor name
    "ui": str,                      # MeSH unique identifier
    "qualifiers": List[Dict]        # Qualifier objects (optional)
}
```

--------------------------------

### Search Articles - Advanced

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-client.md

Performs an advanced search using field tags and date restrictions.

```python
# Advanced search with field tags
articles = await client.search_articles(
    '"breast cancer"[Title] AND 2023[PDAT]',
    max_results=20
)
```

--------------------------------

### PubMedFetch Class Definition

Source: https://github.com/andybrandt/mcp-simple-pubmed/blob/master/_autodocs/api-reference/pubmed-fetch.md

The definition of the PubMedFetch class, which serves as a client for fetching full text from PubMed Central.

```python
class PubMedFetch:
    """Client for fetching full text from PubMed Central."""

```