orcid-mcp-server 1.0.0__tar.gz

orcid_mcp_server-1.0.0/.env.example

@@ -0,0 +1,2 @@
+ORCID_CLIENT_ID=your-client-id-here
+ORCID_CLIENT_SECRET=your-client-secret-here

orcid_mcp_server-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+venv/
+__pycache__/
+*.pyc
+.env
+.claude/
+dist/
+build/
+*.egg-info/
+src/*.egg-info/

orcid_mcp_server-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SMABoundless
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orcid_mcp_server-1.0.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: orcid-mcp-server
+Version: 1.0.0
+Summary: MCP server for the ORCID API — search researchers, read profiles, and export citations
+Project-URL: Repository, https://github.com/SMABoundless/orcid-mcp-server
+Author: SMABoundless
+License-Expression: MIT
+License-File: LICENSE
+Keywords: citations,mcp,orcid,researchers,scholarly
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=1.0.0
+Description-Content-Type: text/markdown
+
+# ORCID MCP Server
+
+An MCP (Model Context Protocol) server that provides tools for searching the [ORCID](https://orcid.org) registry, reading researcher profiles, retrieving publications, and exporting citations in RIS and BibTeX formats.
+
+Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) and the ORCID Public API v3.0.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `orcid_search` | Search for researchers by name, affiliation, keyword, DOI, or advanced Solr query |
+| `orcid_read_record` | Read a researcher's full profile (bio, employment, education, keywords) |
+| `orcid_read_works` | Get publications from a researcher's ORCID record |
+| `orcid_export_ris` | Export retrieved works as RIS (for Zotero, EndNote, etc.) |
+| `orcid_export_bibtex` | Export retrieved works as BibTeX |
+
+## Setup
+
+### 1. Get ORCID API credentials
+
+Register for free public API credentials at [ORCID Developer Tools](https://info.orcid.org/documentation/integration-guide/registering-a-public-api-client/).
+
+### 2. Install
+
+```bash
+cd orcid-mcp-server
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 3. Configure environment
+
+Copy the example env file and add your credentials:
+
+```bash
+cp .env.example .env
+# Edit .env with your ORCID_CLIENT_ID and ORCID_CLIENT_SECRET
+```
+
+### 4. Add to Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "orcid-mcp": {
+      "command": "/path/to/orcid-mcp-server/venv/bin/python",
+      "args": ["/path/to/orcid-mcp-server/server.py"],
+      "env": {
+        "ORCID_CLIENT_ID": "your-client-id",
+        "ORCID_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+Or if using Claude Code CLI:
+
+```bash
+claude mcp add orcid-mcp \
+  /path/to/orcid-mcp-server/venv/bin/python \
+  /path/to/orcid-mcp-server/server.py \
+  -e ORCID_CLIENT_ID=your-client-id \
+  -e ORCID_CLIENT_SECRET=your-client-secret
+```
+
+## Usage examples
+
+Once connected, you can ask Claude things like:
+
+- "Search ORCID for researchers at Northwestern University working on machine learning"
+- "Look up the ORCID profile for 0000-0002-1825-0097"
+- "Get the publications for this researcher and export them as RIS for Zotero"
+
+## License
+
+MIT
+
+<!-- mcp-name: io.github.SMABoundless/orcid -->

orcid_mcp_server-1.0.0/README.md

@@ -0,0 +1,82 @@
+# ORCID MCP Server
+
+An MCP (Model Context Protocol) server that provides tools for searching the [ORCID](https://orcid.org) registry, reading researcher profiles, retrieving publications, and exporting citations in RIS and BibTeX formats.
+
+Built with [FastMCP](https://github.com/modelcontextprotocol/python-sdk) and the ORCID Public API v3.0.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `orcid_search` | Search for researchers by name, affiliation, keyword, DOI, or advanced Solr query |
+| `orcid_read_record` | Read a researcher's full profile (bio, employment, education, keywords) |
+| `orcid_read_works` | Get publications from a researcher's ORCID record |
+| `orcid_export_ris` | Export retrieved works as RIS (for Zotero, EndNote, etc.) |
+| `orcid_export_bibtex` | Export retrieved works as BibTeX |
+
+## Setup
+
+### 1. Get ORCID API credentials
+
+Register for free public API credentials at [ORCID Developer Tools](https://info.orcid.org/documentation/integration-guide/registering-a-public-api-client/).
+
+### 2. Install
+
+```bash
+cd orcid-mcp-server
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### 3. Configure environment
+
+Copy the example env file and add your credentials:
+
+```bash
+cp .env.example .env
+# Edit .env with your ORCID_CLIENT_ID and ORCID_CLIENT_SECRET
+```
+
+### 4. Add to Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "orcid-mcp": {
+      "command": "/path/to/orcid-mcp-server/venv/bin/python",
+      "args": ["/path/to/orcid-mcp-server/server.py"],
+      "env": {
+        "ORCID_CLIENT_ID": "your-client-id",
+        "ORCID_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+Or if using Claude Code CLI:
+
+```bash
+claude mcp add orcid-mcp \
+  /path/to/orcid-mcp-server/venv/bin/python \
+  /path/to/orcid-mcp-server/server.py \
+  -e ORCID_CLIENT_ID=your-client-id \
+  -e ORCID_CLIENT_SECRET=your-client-secret
+```
+
+## Usage examples
+
+Once connected, you can ask Claude things like:
+
+- "Search ORCID for researchers at Northwestern University working on machine learning"
+- "Look up the ORCID profile for 0000-0002-1825-0097"
+- "Get the publications for this researcher and export them as RIS for Zotero"
+
+## License
+
+MIT
+
+<!-- mcp-name: io.github.SMABoundless/orcid -->

orcid_mcp_server-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "orcid-mcp-server"
+version = "1.0.0"
+description = "MCP server for the ORCID API — search researchers, read profiles, and export citations"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "SMABoundless" }]
+keywords = ["mcp", "orcid", "scholarly", "researchers", "citations"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+dependencies = [
+    "mcp[cli]>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+orcid-mcp-server = "orcid_mcp_server:main"
+
+[project.urls]
+Repository = "https://github.com/SMABoundless/orcid-mcp-server"

orcid_mcp_server-1.0.0/requirements.txt

@@ -0,0 +1,2 @@
+mcp
+httpx

orcid_mcp_server-1.0.0/server.py

@@ -0,0 +1,488 @@
+#!/usr/bin/env python3
+"""
+ORCID MCP Server for Claude Desktop
+
+Provides Claude Desktop with tools to search the ORCID registry,
+read researcher profiles, retrieve works, and export citations.
+
+ORCID Public API v3.0 docs:
+  https://github.com/ORCID/ORCID-Source/blob/main/orcid-api-web/README.md
+"""
+
+import os
+from typing import Optional
+from mcp.server.fastmcp import FastMCP
+import httpx
+
+# ── Configuration ──────────────────────────────────────────────────────────
+
+CLIENT_ID = os.environ.get("ORCID_CLIENT_ID", "")
+CLIENT_SECRET = os.environ.get("ORCID_CLIENT_SECRET", "")
+BASE_URL = "https://pub.orcid.org/v3.0"
+TOKEN_URL = "https://orcid.org/oauth/token"
+
+mcp = FastMCP("ORCID")
+
+# ── Token management ──────────────────────────────────────────────────────
+
+_access_token: str = ""
+
+
+async def _get_token() -> str:
+    """Obtain a /read-public access token via client credentials."""
+    global _access_token
+    if _access_token:
+        return _access_token
+
+    async with httpx.AsyncClient(timeout=15) as client:
+        resp = await client.post(
+            TOKEN_URL,
+            data={
+                "client_id": CLIENT_ID,
+                "client_secret": CLIENT_SECRET,
+                "grant_type": "client_credentials",
+                "scope": "/read-public",
+            },
+            headers={"Accept": "application/json"},
+        )
+        resp.raise_for_status()
+        _access_token = resp.json()["access_token"]
+        return _access_token
+
+
+async def _get(url: str, params: dict = None) -> dict:
+    """Make an authenticated GET request to the ORCID API."""
+    token = await _get_token()
+    async with httpx.AsyncClient(timeout=30) as client:
+        resp = await client.get(
+            url,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+            },
+            params=params or {},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────
+
+def _format_search_result(i: int, result: dict) -> str:
+    """Format an expanded-search result."""
+    orcid = result.get("orcid-id", "")
+    given = result.get("given-names", "")
+    family = result.get("family-names", "")
+    credit = result.get("credit-name", "")
+    institutions = result.get("institution-name", [])
+    if isinstance(institutions, str):
+        institutions = [institutions]
+
+    name = credit if credit else f"{given} {family}".strip()
+    line = f"{i}. {name}"
+    if orcid:
+        line += f"\n   ORCID: https://orcid.org/{orcid}"
+    if institutions:
+        line += f"\n   Affiliations: {'; '.join(institutions[:5])}"
+    return line
+
+
+def _format_work(i: int, work_summary: dict) -> str:
+    """Format a single work summary from an ORCID record."""
+    title_obj = work_summary.get("title", {})
+    title = ""
+    if title_obj:
+        title_val = title_obj.get("title", {})
+        title = title_val.get("value", "") if isinstance(title_val, dict) else str(title_val)
+
+    work_type = work_summary.get("type", "")
+    pub_date = work_summary.get("publication-date") or {}
+    year = ""
+    if pub_date and pub_date.get("year"):
+        year = pub_date["year"].get("value", "")
+
+    journal = work_summary.get("journal-title")
+    journal_name = ""
+    if journal:
+        journal_name = journal.get("value", "") if isinstance(journal, dict) else str(journal)
+
+    # External identifiers (DOI, etc.)
+    ext_ids = work_summary.get("external-ids", {})
+    ext_id_list = ext_ids.get("external-id", []) if ext_ids else []
+    doi = ""
+    for eid in ext_id_list:
+        if eid.get("external-id-type") == "doi":
+            doi = eid.get("external-id-value", "")
+            break
+
+    line = f"{i}. {title or 'Untitled'}"
+    if journal_name:
+        line += f"\n   Source: {journal_name}"
+    if year:
+        line += f"\n   Year: {year}"
+    if work_type:
+        line += f"\n   Type: {work_type}"
+    if doi:
+        line += f"\n   DOI: https://doi.org/{doi}"
+    return line
+
+
+def _work_to_ris(work_summary: dict) -> str:
+    """Convert an ORCID work summary to RIS format."""
+    title_obj = work_summary.get("title", {})
+    title = ""
+    if title_obj:
+        title_val = title_obj.get("title", {})
+        title = title_val.get("value", "") if isinstance(title_val, dict) else str(title_val)
+
+    work_type = work_summary.get("type", "")
+    ris_type = "JOUR" if "journal" in work_type.lower() else "GEN"
+
+    pub_date = work_summary.get("publication-date") or {}
+    year = ""
+    if pub_date and pub_date.get("year"):
+        year = pub_date["year"].get("value", "")
+
+    journal = work_summary.get("journal-title")
+    journal_name = ""
+    if journal:
+        journal_name = journal.get("value", "") if isinstance(journal, dict) else str(journal)
+
+    ext_ids = work_summary.get("external-ids", {})
+    ext_id_list = ext_ids.get("external-id", []) if ext_ids else []
+    doi = ""
+    for eid in ext_id_list:
+        if eid.get("external-id-type") == "doi":
+            doi = eid.get("external-id-value", "")
+            break
+
+    lines = [f"TY  - {ris_type}"]
+    if title:
+        lines.append(f"TI  - {title}")
+    if journal_name:
+        lines.append(f"JO  - {journal_name}")
+    if year:
+        lines.append(f"PY  - {year}")
+    if doi:
+        lines.append(f"DO  - {doi}")
+    lines.append("ER  - ")
+    return "\n".join(lines)
+
+
+def _work_to_bibtex(work_summary: dict) -> str:
+    """Convert an ORCID work summary to BibTeX format."""
+    title_obj = work_summary.get("title", {})
+    title = ""
+    if title_obj:
+        title_val = title_obj.get("title", {})
+        title = title_val.get("value", "") if isinstance(title_val, dict) else str(title_val)
+
+    work_type = work_summary.get("type", "")
+    bib_type = "article" if "journal" in work_type.lower() else "misc"
+
+    pub_date = work_summary.get("publication-date") or {}
+    year = ""
+    if pub_date and pub_date.get("year"):
+        year = pub_date["year"].get("value", "")
+
+    journal = work_summary.get("journal-title")
+    journal_name = ""
+    if journal:
+        journal_name = journal.get("value", "") if isinstance(journal, dict) else str(journal)
+
+    ext_ids = work_summary.get("external-ids", {})
+    ext_id_list = ext_ids.get("external-id", []) if ext_ids else []
+    doi = ""
+    for eid in ext_id_list:
+        if eid.get("external-id-type") == "doi":
+            doi = eid.get("external-id-value", "")
+            break
+
+    key = f"orcid{year or 'nd'}"
+    lines = [f"@{bib_type}{{{key},"]
+    if title:
+        lines.append(f"  title = {{{title}}},")
+    if journal_name:
+        lines.append(f"  journal = {{{journal_name}}},")
+    if year:
+        lines.append(f"  year = {{{year}}},")
+    if doi:
+        lines.append(f"  doi = {{{doi}}},")
+    lines.append("}")
+    return "\n".join(lines)
+
+
+# ── Store last works results for export ──────────────────────────────────
+
+_last_works: list = []
+
+
+# ── Tools ─────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+async def orcid_search(
+    query: str,
+    search_type: str = "name",
+    count: int = 25,
+) -> str:
+    """
+    Search the ORCID registry for researchers.
+
+    Args:
+        query: Search terms (name, keyword, affiliation, DOI, ORCID iD)
+        search_type: One of: name, affiliation, keyword, doi, advanced
+                     - name: searches by researcher name
+                     - affiliation: searches by institution/organization name
+                     - keyword: searches researcher keywords/biography
+                     - doi: finds the ORCID record linked to a specific DOI
+                     - advanced: pass raw Solr query (e.g. "family-name:Einstein AND keyword:Relativity")
+        count: Number of results (max 100, default 25)
+    """
+    query_map = {
+        "name": lambda q: f"given-and-family-names:{q}",
+        "affiliation": lambda q: f"affiliation-org-name:{q}",
+        "keyword": lambda q: f"keyword:{q}",
+        "doi": lambda q: f'doi-self:"{q}"',
+        "advanced": lambda q: q,
+    }
+    builder = query_map.get(search_type, query_map["name"])
+    solr_query = builder(query)
+
+    try:
+        data = await _get(
+            f"{BASE_URL}/expanded-search/",
+            {"q": solr_query, "rows": min(count, 100), "start": 0},
+        )
+
+        results = data.get("expanded-result", [])
+        total = data.get("num-found", 0)
+
+        if not results:
+            return f"No results found for: {query}"
+
+        header = f"ORCID Search: {total} total results, showing {len(results)}\n"
+        header += f"Query: {solr_query}\n"
+        header += "=" * 60 + "\n\n"
+        formatted = "\n\n".join(
+            _format_search_result(i, r) for i, r in enumerate(results, 1)
+        )
+        return header + formatted
+    except httpx.HTTPStatusError as e:
+        return f"ORCID API error: {e.response.status_code} — {e.response.text}"
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+@mcp.tool()
+async def orcid_read_record(orcid_id: str) -> str:
+    """
+    Read a researcher's full ORCID profile.
+
+    Args:
+        orcid_id: The ORCID iD (e.g. "0000-0002-1825-0097")
+    """
+    try:
+        data = await _get(f"{BASE_URL}/{orcid_id}/record")
+
+        # Person details
+        person = data.get("person", {})
+        name_obj = person.get("name", {})
+        given = ""
+        family = ""
+        credit = ""
+        if name_obj:
+            gn = name_obj.get("given-names")
+            given = gn.get("value", "") if isinstance(gn, dict) else (gn or "")
+            fn = name_obj.get("family-name")
+            family = fn.get("value", "") if isinstance(fn, dict) else (fn or "")
+            cn = name_obj.get("credit-name")
+            credit = cn.get("value", "") if isinstance(cn, dict) else (cn or "")
+
+        bio_obj = person.get("biography")
+        bio = ""
+        if bio_obj:
+            bio = bio_obj.get("content", "") if isinstance(bio_obj, dict) else str(bio_obj)
+
+        # Keywords
+        kw_obj = person.get("keywords", {})
+        kw_list = kw_obj.get("keyword", []) if kw_obj else []
+        keywords = [k.get("content", "") for k in kw_list if k.get("content")]
+
+        # Researcher URLs
+        urls_obj = person.get("researcher-urls", {})
+        url_list = urls_obj.get("researcher-url", []) if urls_obj else []
+        urls = [(u.get("url-name", ""), u.get("url", {}).get("value", "")) for u in url_list]
+
+        # Emails
+        emails_obj = person.get("emails", {})
+        email_list = emails_obj.get("email", []) if emails_obj else []
+        emails = [e.get("email", "") for e in email_list if e.get("email")]
+
+        # Activities summary
+        activities = data.get("activities-summary", {})
+
+        # Employments
+        emp_obj = activities.get("employments", {})
+        emp_groups = emp_obj.get("affiliation-group", []) if emp_obj else []
+        employments = []
+        for group in emp_groups:
+            summaries = group.get("summaries", [])
+            for s in summaries:
+                emp = s.get("employment-summary", {})
+                org = emp.get("organization", {})
+                org_name = org.get("name", "")
+                role = emp.get("role-title", "")
+                dept = emp.get("department-name", "")
+                start = emp.get("start-date")
+                end = emp.get("end-date")
+                start_yr = start.get("year", {}).get("value", "") if start else ""
+                end_yr = end.get("year", {}).get("value", "present") if end else "present"
+                entry = org_name
+                if role:
+                    entry = f"{role}, {entry}"
+                if dept:
+                    entry += f" ({dept})"
+                if start_yr:
+                    entry += f" [{start_yr}–{end_yr}]"
+                employments.append(entry)
+
+        # Educations
+        edu_obj = activities.get("educations", {})
+        edu_groups = edu_obj.get("affiliation-group", []) if edu_obj else []
+        educations = []
+        for group in edu_groups:
+            summaries = group.get("summaries", [])
+            for s in summaries:
+                edu = s.get("education-summary", {})
+                org = edu.get("organization", {})
+                org_name = org.get("name", "")
+                role = edu.get("role-title", "")
+                dept = edu.get("department-name", "")
+                start = edu.get("start-date")
+                end = edu.get("end-date")
+                start_yr = start.get("year", {}).get("value", "") if start else ""
+                end_yr = end.get("year", {}).get("value", "") if end else ""
+                entry = org_name
+                if role:
+                    entry = f"{role}, {entry}"
+                if dept:
+                    entry += f" ({dept})"
+                if start_yr:
+                    entry += f" [{start_yr}–{end_yr}]" if end_yr else f" [{start_yr}–]"
+                educations.append(entry)
+
+        # Works count
+        works_obj = activities.get("works", {})
+        work_groups = works_obj.get("group", []) if works_obj else []
+        works_count = len(work_groups)
+
+        # Fundings count
+        fund_obj = activities.get("fundings", {})
+        fund_groups = fund_obj.get("group", []) if fund_obj else []
+        fundings_count = len(fund_groups)
+
+        # Build output
+        display_name = credit if credit else f"{given} {family}".strip()
+        output = f"Name: {display_name}\n"
+        output += f"ORCID: https://orcid.org/{orcid_id}\n"
+        if emails:
+            output += f"Email: {'; '.join(emails)}\n"
+        if bio:
+            output += f"\nBiography:\n{bio}\n"
+        if keywords:
+            output += f"\nKeywords: {'; '.join(keywords)}\n"
+        if urls:
+            output += "\nLinks:\n"
+            for name, url in urls:
+                output += f"  - {name}: {url}\n" if name else f"  - {url}\n"
+        if employments:
+            output += f"\nEmployment ({len(employments)}):\n"
+            for emp in employments:
+                output += f"  - {emp}\n"
+        if educations:
+            output += f"\nEducation ({len(educations)}):\n"
+            for edu in educations:
+                output += f"  - {edu}\n"
+        output += f"\nWorks: {works_count} items"
+        if works_count > 0:
+            output += " (use orcid_read_works to see them)"
+        output += f"\nFunding: {fundings_count} items"
+
+        return output
+    except httpx.HTTPStatusError as e:
+        return f"ORCID API error: {e.response.status_code} — {e.response.text}"
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+@mcp.tool()
+async def orcid_read_works(
+    orcid_id: str,
+    count: int = 25,
+) -> str:
+    """
+    Get publications from an ORCID researcher profile.
+
+    Args:
+        orcid_id: The ORCID iD (e.g. "0000-0002-1825-0097")
+        count: Maximum number of works to return (default 25)
+    """
+    global _last_works
+    try:
+        data = await _get(f"{BASE_URL}/{orcid_id}/works")
+        groups = data.get("group", [])
+
+        if not groups:
+            _last_works = []
+            return f"No works found for ORCID {orcid_id}"
+
+        # Each group has work-summary entries; take the first summary per group
+        works = []
+        for group in groups[:count]:
+            summaries = group.get("work-summary", [])
+            if summaries:
+                works.append(summaries[0])
+
+        _last_works = works
+
+        header = f"Works for ORCID {orcid_id}: {len(groups)} total, showing {len(works)}\n"
+        header += "=" * 60 + "\n\n"
+        formatted = "\n\n".join(
+            _format_work(i, w) for i, w in enumerate(works, 1)
+        )
+        return header + formatted
+    except httpx.HTTPStatusError as e:
+        return f"ORCID API error: {e.response.status_code} — {e.response.text}"
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+@mcp.tool()
+async def orcid_export_ris() -> str:
+    """
+    Export the most recent orcid_read_works results as RIS format.
+    Save output as a .ris file and import into Zotero: File -> Import.
+    """
+    if not _last_works:
+        return "No works to export. Run orcid_read_works first."
+    records = [_work_to_ris(w) for w in _last_works]
+    count = len(records)
+    return f"RIS Export ({count} records) — Save as .ris and import into Zotero:\n\n" + "\n\n".join(records)
+
+
+@mcp.tool()
+async def orcid_export_bibtex() -> str:
+    """
+    Export the most recent orcid_read_works results as BibTeX format.
+    """
+    if not _last_works:
+        return "No works to export. Run orcid_read_works first."
+    records = [_work_to_bibtex(w) for w in _last_works]
+    count = len(records)
+    return f"BibTeX Export ({count} records):\n\n" + "\n\n".join(records)
+
+
+# ── Run ────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    mcp.run()

orcid_mcp_server-1.0.0/src/orcid_mcp_server/__init__.py

@@ -0,0 +1,4 @@
+from .server import mcp
+
+def main():
+    mcp.run()

orcid_mcp_server-1.0.0/src/orcid_mcp_server/server.py

@@ -0,0 +1,488 @@
+#!/usr/bin/env python3
+"""
+ORCID MCP Server for Claude Desktop
+
+Provides Claude Desktop with tools to search the ORCID registry,
+read researcher profiles, retrieve works, and export citations.
+
+ORCID Public API v3.0 docs:
+  https://github.com/ORCID/ORCID-Source/blob/main/orcid-api-web/README.md
+"""
+
+import os
+from typing import Optional
+from mcp.server.fastmcp import FastMCP
+import httpx
+
+# ── Configuration ──────────────────────────────────────────────────────────
+
+CLIENT_ID = os.environ.get("ORCID_CLIENT_ID", "")
+CLIENT_SECRET = os.environ.get("ORCID_CLIENT_SECRET", "")
+BASE_URL = "https://pub.orcid.org/v3.0"
+TOKEN_URL = "https://orcid.org/oauth/token"
+
+mcp = FastMCP("ORCID")
+
+# ── Token management ──────────────────────────────────────────────────────
+
+_access_token: str = ""
+
+
+async def _get_token() -> str:
+    """Obtain a /read-public access token via client credentials."""
+    global _access_token
+    if _access_token:
+        return _access_token
+
+    async with httpx.AsyncClient(timeout=15) as client:
+        resp = await client.post(
+            TOKEN_URL,
+            data={
+                "client_id": CLIENT_ID,
+                "client_secret": CLIENT_SECRET,
+                "grant_type": "client_credentials",
+                "scope": "/read-public",
+            },
+            headers={"Accept": "application/json"},
+        )
+        resp.raise_for_status()
+        _access_token = resp.json()["access_token"]
+        return _access_token
+
+
+async def _get(url: str, params: dict = None) -> dict:
+    """Make an authenticated GET request to the ORCID API."""
+    token = await _get_token()
+    async with httpx.AsyncClient(timeout=30) as client:
+        resp = await client.get(
+            url,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+            },
+            params=params or {},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────
+
+def _format_search_result(i: int, result: dict) -> str:
+    """Format an expanded-search result."""
+    orcid = result.get("orcid-id", "")
+    given = result.get("given-names", "")
+    family = result.get("family-names", "")
+    credit = result.get("credit-name", "")
+    institutions = result.get("institution-name", [])
+    if isinstance(institutions, str):
+        institutions = [institutions]
+
+    name = credit if credit else f"{given} {family}".strip()
+    line = f"{i}. {name}"
+    if orcid:
+        line += f"\n   ORCID: https://orcid.org/{orcid}"
+    if institutions:
+        line += f"\n   Affiliations: {'; '.join(institutions[:5])}"
+    return line
+
+
+def _format_work(i: int, work_summary: dict) -> str:
+    """Format a single work summary from an ORCID record."""
+    title_obj = work_summary.get("title", {})
+    title = ""
+    if title_obj:
+        title_val = title_obj.get("title", {})
+        title = title_val.get("value", "") if isinstance(title_val, dict) else str(title_val)
+
+    work_type = work_summary.get("type", "")
+    pub_date = work_summary.get("publication-date") or {}
+    year = ""
+    if pub_date and pub_date.get("year"):
+        year = pub_date["year"].get("value", "")
+
+    journal = work_summary.get("journal-title")
+    journal_name = ""
+    if journal:
+        journal_name = journal.get("value", "") if isinstance(journal, dict) else str(journal)
+
+    # External identifiers (DOI, etc.)
+    ext_ids = work_summary.get("external-ids", {})
+    ext_id_list = ext_ids.get("external-id", []) if ext_ids else []
+    doi = ""
+    for eid in ext_id_list:
+        if eid.get("external-id-type") == "doi":
+            doi = eid.get("external-id-value", "")
+            break
+
+    line = f"{i}. {title or 'Untitled'}"
+    if journal_name:
+        line += f"\n   Source: {journal_name}"
+    if year:
+        line += f"\n   Year: {year}"
+    if work_type:
+        line += f"\n   Type: {work_type}"
+    if doi:
+        line += f"\n   DOI: https://doi.org/{doi}"
+    return line
+
+
+def _work_to_ris(work_summary: dict) -> str:
+    """Convert an ORCID work summary to RIS format."""
+    title_obj = work_summary.get("title", {})
+    title = ""
+    if title_obj:
+        title_val = title_obj.get("title", {})
+        title = title_val.get("value", "") if isinstance(title_val, dict) else str(title_val)
+
+    work_type = work_summary.get("type", "")
+    ris_type = "JOUR" if "journal" in work_type.lower() else "GEN"
+
+    pub_date = work_summary.get("publication-date") or {}
+    year = ""
+    if pub_date and pub_date.get("year"):
+        year = pub_date["year"].get("value", "")
+
+    journal = work_summary.get("journal-title")
+    journal_name = ""
+    if journal:
+        journal_name = journal.get("value", "") if isinstance(journal, dict) else str(journal)
+
+    ext_ids = work_summary.get("external-ids", {})
+    ext_id_list = ext_ids.get("external-id", []) if ext_ids else []
+    doi = ""
+    for eid in ext_id_list:
+        if eid.get("external-id-type") == "doi":
+            doi = eid.get("external-id-value", "")
+            break
+
+    lines = [f"TY  - {ris_type}"]
+    if title:
+        lines.append(f"TI  - {title}")
+    if journal_name:
+        lines.append(f"JO  - {journal_name}")
+    if year:
+        lines.append(f"PY  - {year}")
+    if doi:
+        lines.append(f"DO  - {doi}")
+    lines.append("ER  - ")
+    return "\n".join(lines)
+
+
+def _work_to_bibtex(work_summary: dict) -> str:
+    """Convert an ORCID work summary to BibTeX format."""
+    title_obj = work_summary.get("title", {})
+    title = ""
+    if title_obj:
+        title_val = title_obj.get("title", {})
+        title = title_val.get("value", "") if isinstance(title_val, dict) else str(title_val)
+
+    work_type = work_summary.get("type", "")
+    bib_type = "article" if "journal" in work_type.lower() else "misc"
+
+    pub_date = work_summary.get("publication-date") or {}
+    year = ""
+    if pub_date and pub_date.get("year"):
+        year = pub_date["year"].get("value", "")
+
+    journal = work_summary.get("journal-title")
+    journal_name = ""
+    if journal:
+        journal_name = journal.get("value", "") if isinstance(journal, dict) else str(journal)
+
+    ext_ids = work_summary.get("external-ids", {})
+    ext_id_list = ext_ids.get("external-id", []) if ext_ids else []
+    doi = ""
+    for eid in ext_id_list:
+        if eid.get("external-id-type") == "doi":
+            doi = eid.get("external-id-value", "")
+            break
+
+    key = f"orcid{year or 'nd'}"
+    lines = [f"@{bib_type}{{{key},"]
+    if title:
+        lines.append(f"  title = {{{title}}},")
+    if journal_name:
+        lines.append(f"  journal = {{{journal_name}}},")
+    if year:
+        lines.append(f"  year = {{{year}}},")
+    if doi:
+        lines.append(f"  doi = {{{doi}}},")
+    lines.append("}")
+    return "\n".join(lines)
+
+
+# ── Store last works results for export ──────────────────────────────────
+
+_last_works: list = []
+
+
+# ── Tools ─────────────────────────────────────────────────────────────────
+
+@mcp.tool()
+async def orcid_search(
+    query: str,
+    search_type: str = "name",
+    count: int = 25,
+) -> str:
+    """
+    Search the ORCID registry for researchers.
+
+    Args:
+        query: Search terms (name, keyword, affiliation, DOI, ORCID iD)
+        search_type: One of: name, affiliation, keyword, doi, advanced
+                     - name: searches by researcher name
+                     - affiliation: searches by institution/organization name
+                     - keyword: searches researcher keywords/biography
+                     - doi: finds the ORCID record linked to a specific DOI
+                     - advanced: pass raw Solr query (e.g. "family-name:Einstein AND keyword:Relativity")
+        count: Number of results (max 100, default 25)
+    """
+    query_map = {
+        "name": lambda q: f"given-and-family-names:{q}",
+        "affiliation": lambda q: f"affiliation-org-name:{q}",
+        "keyword": lambda q: f"keyword:{q}",
+        "doi": lambda q: f'doi-self:"{q}"',
+        "advanced": lambda q: q,
+    }
+    builder = query_map.get(search_type, query_map["name"])
+    solr_query = builder(query)
+
+    try:
+        data = await _get(
+            f"{BASE_URL}/expanded-search/",
+            {"q": solr_query, "rows": min(count, 100), "start": 0},
+        )
+
+        results = data.get("expanded-result", [])
+        total = data.get("num-found", 0)
+
+        if not results:
+            return f"No results found for: {query}"
+
+        header = f"ORCID Search: {total} total results, showing {len(results)}\n"
+        header += f"Query: {solr_query}\n"
+        header += "=" * 60 + "\n\n"
+        formatted = "\n\n".join(
+            _format_search_result(i, r) for i, r in enumerate(results, 1)
+        )
+        return header + formatted
+    except httpx.HTTPStatusError as e:
+        return f"ORCID API error: {e.response.status_code} — {e.response.text}"
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+@mcp.tool()
+async def orcid_read_record(orcid_id: str) -> str:
+    """
+    Read a researcher's full ORCID profile.
+
+    Args:
+        orcid_id: The ORCID iD (e.g. "0000-0002-1825-0097")
+    """
+    try:
+        data = await _get(f"{BASE_URL}/{orcid_id}/record")
+
+        # Person details
+        person = data.get("person", {})
+        name_obj = person.get("name", {})
+        given = ""
+        family = ""
+        credit = ""
+        if name_obj:
+            gn = name_obj.get("given-names")
+            given = gn.get("value", "") if isinstance(gn, dict) else (gn or "")
+            fn = name_obj.get("family-name")
+            family = fn.get("value", "") if isinstance(fn, dict) else (fn or "")
+            cn = name_obj.get("credit-name")
+            credit = cn.get("value", "") if isinstance(cn, dict) else (cn or "")
+
+        bio_obj = person.get("biography")
+        bio = ""
+        if bio_obj:
+            bio = bio_obj.get("content", "") if isinstance(bio_obj, dict) else str(bio_obj)
+
+        # Keywords
+        kw_obj = person.get("keywords", {})
+        kw_list = kw_obj.get("keyword", []) if kw_obj else []
+        keywords = [k.get("content", "") for k in kw_list if k.get("content")]
+
+        # Researcher URLs
+        urls_obj = person.get("researcher-urls", {})
+        url_list = urls_obj.get("researcher-url", []) if urls_obj else []
+        urls = [(u.get("url-name", ""), u.get("url", {}).get("value", "")) for u in url_list]
+
+        # Emails
+        emails_obj = person.get("emails", {})
+        email_list = emails_obj.get("email", []) if emails_obj else []
+        emails = [e.get("email", "") for e in email_list if e.get("email")]
+
+        # Activities summary
+        activities = data.get("activities-summary", {})
+
+        # Employments
+        emp_obj = activities.get("employments", {})
+        emp_groups = emp_obj.get("affiliation-group", []) if emp_obj else []
+        employments = []
+        for group in emp_groups:
+            summaries = group.get("summaries", [])
+            for s in summaries:
+                emp = s.get("employment-summary", {})
+                org = emp.get("organization", {})
+                org_name = org.get("name", "")
+                role = emp.get("role-title", "")
+                dept = emp.get("department-name", "")
+                start = emp.get("start-date")
+                end = emp.get("end-date")
+                start_yr = start.get("year", {}).get("value", "") if start else ""
+                end_yr = end.get("year", {}).get("value", "present") if end else "present"
+                entry = org_name
+                if role:
+                    entry = f"{role}, {entry}"
+                if dept:
+                    entry += f" ({dept})"
+                if start_yr:
+                    entry += f" [{start_yr}–{end_yr}]"
+                employments.append(entry)
+
+        # Educations
+        edu_obj = activities.get("educations", {})
+        edu_groups = edu_obj.get("affiliation-group", []) if edu_obj else []
+        educations = []
+        for group in edu_groups:
+            summaries = group.get("summaries", [])
+            for s in summaries:
+                edu = s.get("education-summary", {})
+                org = edu.get("organization", {})
+                org_name = org.get("name", "")
+                role = edu.get("role-title", "")
+                dept = edu.get("department-name", "")
+                start = edu.get("start-date")
+                end = edu.get("end-date")
+                start_yr = start.get("year", {}).get("value", "") if start else ""
+                end_yr = end.get("year", {}).get("value", "") if end else ""
+                entry = org_name
+                if role:
+                    entry = f"{role}, {entry}"
+                if dept:
+                    entry += f" ({dept})"
+                if start_yr:
+                    entry += f" [{start_yr}–{end_yr}]" if end_yr else f" [{start_yr}–]"
+                educations.append(entry)
+
+        # Works count
+        works_obj = activities.get("works", {})
+        work_groups = works_obj.get("group", []) if works_obj else []
+        works_count = len(work_groups)
+
+        # Fundings count
+        fund_obj = activities.get("fundings", {})
+        fund_groups = fund_obj.get("group", []) if fund_obj else []
+        fundings_count = len(fund_groups)
+
+        # Build output
+        display_name = credit if credit else f"{given} {family}".strip()
+        output = f"Name: {display_name}\n"
+        output += f"ORCID: https://orcid.org/{orcid_id}\n"
+        if emails:
+            output += f"Email: {'; '.join(emails)}\n"
+        if bio:
+            output += f"\nBiography:\n{bio}\n"
+        if keywords:
+            output += f"\nKeywords: {'; '.join(keywords)}\n"
+        if urls:
+            output += "\nLinks:\n"
+            for name, url in urls:
+                output += f"  - {name}: {url}\n" if name else f"  - {url}\n"
+        if employments:
+            output += f"\nEmployment ({len(employments)}):\n"
+            for emp in employments:
+                output += f"  - {emp}\n"
+        if educations:
+            output += f"\nEducation ({len(educations)}):\n"
+            for edu in educations:
+                output += f"  - {edu}\n"
+        output += f"\nWorks: {works_count} items"
+        if works_count > 0:
+            output += " (use orcid_read_works to see them)"
+        output += f"\nFunding: {fundings_count} items"
+
+        return output
+    except httpx.HTTPStatusError as e:
+        return f"ORCID API error: {e.response.status_code} — {e.response.text}"
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+@mcp.tool()
+async def orcid_read_works(
+    orcid_id: str,
+    count: int = 25,
+) -> str:
+    """
+    Get publications from an ORCID researcher profile.
+
+    Args:
+        orcid_id: The ORCID iD (e.g. "0000-0002-1825-0097")
+        count: Maximum number of works to return (default 25)
+    """
+    global _last_works
+    try:
+        data = await _get(f"{BASE_URL}/{orcid_id}/works")
+        groups = data.get("group", [])
+
+        if not groups:
+            _last_works = []
+            return f"No works found for ORCID {orcid_id}"
+
+        # Each group has work-summary entries; take the first summary per group
+        works = []
+        for group in groups[:count]:
+            summaries = group.get("work-summary", [])
+            if summaries:
+                works.append(summaries[0])
+
+        _last_works = works
+
+        header = f"Works for ORCID {orcid_id}: {len(groups)} total, showing {len(works)}\n"
+        header += "=" * 60 + "\n\n"
+        formatted = "\n\n".join(
+            _format_work(i, w) for i, w in enumerate(works, 1)
+        )
+        return header + formatted
+    except httpx.HTTPStatusError as e:
+        return f"ORCID API error: {e.response.status_code} — {e.response.text}"
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+
+@mcp.tool()
+async def orcid_export_ris() -> str:
+    """
+    Export the most recent orcid_read_works results as RIS format.
+    Save output as a .ris file and import into Zotero: File -> Import.
+    """
+    if not _last_works:
+        return "No works to export. Run orcid_read_works first."
+    records = [_work_to_ris(w) for w in _last_works]
+    count = len(records)
+    return f"RIS Export ({count} records) — Save as .ris and import into Zotero:\n\n" + "\n\n".join(records)
+
+
+@mcp.tool()
+async def orcid_export_bibtex() -> str:
+    """
+    Export the most recent orcid_read_works results as BibTeX format.
+    """
+    if not _last_works:
+        return "No works to export. Run orcid_read_works first."
+    records = [_work_to_bibtex(w) for w in _last_works]
+    count = len(records)
+    return f"BibTeX Export ({count} records):\n\n" + "\n\n".join(records)
+
+
+# ── Run ────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    mcp.run()