Metadata-Version: 2.4
Name: mcp-server-pubmed
Version: 0.0.1
Summary: Fork of JackKuo666/PubMed-MCP-Server: an MCP server for searching biomedical articles via the Europe PMC REST API (drop-in replacement for the NCBI E-utilities backend)
License-Expression: MIT
Project-URL: Upstream project, https://github.com/JackKuo666/PubMed-MCP-Server
Keywords: mcp,pubmed,europe-pmc,biomedical,literature-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.4.1
Requires-Dist: requests>=2.25.1
Dynamic: license-file

[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/jackkuo666-pubmed-mcp-server-badge.png)](https://mseep.ai/app/jackkuo666-pubmed-mcp-server)

# PubMed MCP Server

[![smithery badge](https://smithery.ai/badge/@JackKuo666/pubmed-mcp-server)](https://smithery.ai/server/@JackKuo666/pubmed-mcp-server)

🔍 Enable AI assistants to search, access, and analyze PubMed articles through a simple MCP interface.

The PubMed MCP Server provides a bridge between AI assistants and PubMed's vast repository of biomedical literature through the Model Context Protocol (MCP). It allows AI models to search for scientific articles, access their metadata, and perform deep analysis in a programmatic way.

🤝 Contribute • 📝 Report Bug

## 🔄 Europe PMC backend (v0.0.1)

This fork ships an additional `pubmed_mcp_server` package whose search backend is the
**Europe PMC REST API** (`https://www.ebi.ac.uk/europepmc/webservices/rest/search`) instead of
NCBI E-utilities.

### Why Europe PMC replaces NCBI

When the server runs inside a sandbox / cloud environment (e.g. the ROCK sandbox), NCBI
E-utilities frequently rate-limits or blocks the shared egress IP and returns an HTML error page.
The upstream code feeds that HTML into an XML parser, so the tool call fails with:

```text
Error executing tool search_pubmed_articles: mismatched tag: line 198, column 2
```

Europe PMC stays reachable from those environments, requires no API key, and covers PubMed
content (`source: MED`) plus preprints, patents and Agricola records — so results are functionally
equivalent to PubMed for most biomedical queries.

### What changed

- Replaced the NCBI `esearch` + `efetch` XML flow with the Europe PMC REST API (`format=json`,
  `resultType=core`).
- Parses the Europe PMC JSON shape, including `journalInfo.journal.title`, `authorList`
  (with `authorString` fallback), `pubYear`/`pubMonth`/`pubDay` and `abstractText`.
- Keeps `User-Agent` / `Accept` headers, connect/read timeouts `(10, 30)` and retry with
  exponential backoff on `429/500/502/503`.
- Preserves the original tool signature `search_pubmed_articles(query, api_key=None)` so existing
  demos keep working. `api_key` is accepted for compatibility but unused (Europe PMC needs none).

### Local verification

```bash
# run the search layer directly
uv run --with requests python pubmed_mcp_server/pubmed.py

# or start the MCP server from a local checkout
uvx --from . --with "mcp<2" pubmed_mcp_server
```

## ✨ Core Features

- 🔎 Paper Search: Query PubMed articles with keywords or advanced search ✅
- 🚀 Efficient Retrieval: Fast access to paper metadata ✅
- 📊 Metadata Access: Retrieve detailed metadata for specific papers ✅
- 📊 Research Support: Facilitate biomedical sciences research and analysis ✅
- 📄 Paper Access: Attempt to download full-text PDF content ✅
- 🧠 Deep Analysis: Perform comprehensive analysis of papers ✅
- 📝 Research Prompts: A set of specialized prompts for paper analysis ✅

## 🚀 Quick Start

### Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) (for the recommended `uvx` install), or FastMCP installed manually

### Recommended: run straight from Git with `uvx` (no clone, no install)

This fork is packaged so any MCP client can launch it directly from the Git URL — `uvx` clones the
repo, builds the `pubmed_mcp_server` package and runs its console script:

```bash
uvx --from "git+https://github.com/yourname/pubmed-mcp-server.git@<commit-or-tag>" \
    --with "mcp<2" pubmed_mcp_server
```

As an MCP client config (Claude Desktop, Cursor, Cline, ROCK `McpEnv`, …):

```json
{
  "mcpServers": {
    "pubmed": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/yourname/pubmed-mcp-server.git@<commit-or-tag>",
        "--with",
        "mcp<2",
        "pubmed_mcp_server"
      ]
    }
  }
}
```

This exposes the `search_pubmed_articles` tool and requires **no API key**. `@<commit-or-tag>` is
optional but recommended for reproducible installs — see
[Use in a sandbox via `git+https`](#-use-in-a-sandbox-via-githttps) for how to publish and pin it.

### Installation

### Installing via Smithery

To install pubmed-mcp-server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@JackKuo666/pubmed-mcp-server):

#### claude

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

#### Cursor

Paste the following into Settings → Cursor Settings → MCP → Add new server:

- Mac/Linux

```s
npx -y @smithery/cli@latest run @JackKuo666/pubmed-mcp-server --client cursor --config "{}"
```

#### Windsurf

```sh
npx -y @smithery/cli@latest install @JackKuo666/pubmed-mcp-server --client windsurf --config "{}"
```

### CLine

```sh
npx -y @smithery/cli@latest install @JackKuo666/pubmed-mcp-server --client cline --config "{}"
```

> Note: the Smithery entries above install the **upstream** package, which still uses the NCBI
> E-utilities backend. Use the `uvx --from git+https://...` config above to get this fork's
> Europe PMC backend.

1. Clone the repository:

   ```
   git clone https://github.com/JackKuo666/PubMed-MCP-Server.git
   cd PubMed-MCP-Server
   ```

2. Install the required dependencies:
   ```
   pip install -r requirements.txt
   ```

## 📊 Usage

Start the Europe PMC server from a clone:

```bash
uvx --from . --with "mcp<2" pubmed_mcp_server
```

Or start the legacy (NCBI-backed) server:

```bash
python pubmed_server.py
```

## Usage with Claude Desktop

Add this configuration to your `claude_desktop_config.json`:

(Mac OS)

```json
{
  "mcpServers": {
    "pubmed": {
      "command": "python",
      "args": ["-m", "pubmed-mcp-server"]
    }
  }
}
```

(Windows version):

```json
{
  "mcpServers": {
    "pubmed": {
      "command": "C:\\Users\\YOUR\\PATH\\miniconda3\\envs\\mcp_server\\python.exe",
      "args": ["D:\\code\\YOUR\\PATH\\PubMed-MCP-Server\\pubmed_server.py"],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

Using with Cline

```json
{
  "mcpServers": {
    "pubmed": {
      "command": "bash",
      "args": [
        "-c",
        "source /home/YOUR/PATH/mcp-server-pubmed/.venv/bin/activate && python /home/YOUR/PATH/pubmed-mcp-server.py"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

## 🛠 MCP Tools

The PubMed MCP Server provides the following tools:

1. `search_pubmed_key_words`: Search for articles on PubMed using keywords.
2. `search_pubmed_advanced`: Perform an advanced search for articles on PubMed with multiple parameters.
3. `get_pubmed_article_metadata`: Fetch metadata for a PubMed article using its PMID.
4. `download_pubmed_pdf`: Attempt to download the full-text PDF for a PubMed article.
5. `deep_paper_analysis`: Perform a comprehensive analysis of a PubMed article.

The Europe PMC package (`pubmed_mcp_server`) exposes:

1. `search_pubmed_articles(query, api_key=None)`: Search articles through Europe PMC.
2. `convert_to_pubmed_query` (prompt): Turn a natural language question into PubMed search syntax.
3. `article://{pmid}` (resource): Fetch a single article by PMID.

### Searching Papers

You can ask the AI assistant to search for papers using queries like:

```
Can you search PubMed for recent papers about CRISPR?
```

### Getting Paper Details

Once you have a PMID, you can ask for more details:

```
Can you show me the metadata for the paper with PMID 12345678?
```

### Analyzing Papers

You can request a deep analysis of a paper:

```
Can you perform a deep analysis of the paper with PMID 12345678?
```

## 📦 Use in a sandbox via `git+https`

`uvx --from <local-path>` does **not** expose tools correctly when run inside the ROCK sandbox (the
server starts but lists 0 tools). Publish this repository to Git and install it via `git+https`
instead.

### Upload to GitHub

1. Create a new public GitHub repository, e.g. `yourname/pubmed-mcp-server`.
2. From this project root, push the code:

   ```bash
   git init
   git add pyproject.toml README.md requirements.txt pubmed_mcp_server pubmed_server.py pubmed_web_search.py
   git commit -m "Switch PubMed MCP server backend to Europe PMC"
   git branch -M main
   git remote add origin https://github.com/yourname/pubmed-mcp-server.git
   git push -u origin main
   ```

3. Note the pushed commit SHA (or create a tag such as `v0.0.1`) — pin it in the client config so
   the sandbox always installs a reproducible revision:

   ```bash
   git rev-parse --short HEAD
   # or
   git tag v0.0.1 && git push origin v0.0.1
   ```

The repository root must contain `pyproject.toml` and the `pubmed_mcp_server/` package
(`__init__.py`, `main.py`, `pubmed.py`), which is what the `pubmed_mcp_server` entry point resolves
to.

### Config to fill into `pubmed/demo.py`

```python
PUBMED_SERVER_CONFIG = {
    "command": "uvx",
    "args": [
        "--from",
        "git+https://github.com/yourname/pubmed-mcp-server.git@<commit-or-tag>",
        "--with",
        "mcp<2",
        "pubmed_mcp_server",
    ],
}
```

Then call the tool:

```python
result = await session.call_tool(
    "search_pubmed_articles", arguments={"query": "cancer immunotherapy"}
)
```

No API key is required.

## 📁 Project Structure

- `pubmed_mcp_server/pubmed.py`: Europe PMC REST search layer (retries, timeouts, JSON parsing)
- `pubmed_mcp_server/main.py`: FastMCP server exposing `search_pubmed_articles`
- `pubmed_server.py`: The original upstream MCP server implementation using FastMCP
- `pubmed_web_search.py`: The original NCBI E-utilities logic used by `pubmed_server.py`

## 🔧 Dependencies

- Python 3.10+
- FastMCP (`mcp`)
- requests
- asyncio, logging (standard library)
- beautifulsoup4 (only needed for the legacy `pubmed_server.py` entry point)

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

This project is licensed under the MIT License.

## ⚠️ Disclaimer

This tool is for research purposes only. Please respect PubMed's and Europe PMC's terms of service and use this tool responsibly.

If you need direct NCBI E-utilities access, run the legacy `pubmed_server.py` outside the sandbox,
or use an NCBI API key from an unblocked IP.
