Skip to main content
Glama

MeSH MCP

An experimental MCP (Model Context Protocol) server connecting Claude to the U.S. National Library of Medicine (NLM) Medical Subject Headings (MeSH) linked data APIs, built to investigate the potential of large language models in subject analysis and authority control.


What This Server Does

MeSH MCP connects Claude Desktop to the NLM MeSH APIs, allowing you to search and retrieve MeSH authority data directly within your AI-assisted cataloging workflow.

Once installed, you can ask Claude things like:

  • "Search MeSH for terms related to osmotic stress"

  • "Find the MeSH descriptor for CRISPR gene editing"

  • "What is the scope note for this MeSH descriptor?"

  • "Look up the full record for descriptor D011506"

The server handles all the API calls, parses the responses, and returns structured data Claude can reason about.


Related MCP server: OMOPHub MCP Server

Who This Is For

  • Catalogers and metadata staff using Claude Desktop who want AI-assisted subject description grounded in real MeSH vocabulary data

  • Library and repository staff working with health sciences or biomedical research outputs — theses, datasets, grey literature — where MeSH is the preferred controlled vocabulary

  • Developers integrating MeSH lookups into MCP-based systems


Tools

Tool

Description

search_mesh

Search MeSH descriptors by label using the NLM lookup autocomplete endpoint. Supports startsWith (default), contains, and exact matching. Returns a list of {label, ui, uri} dicts.

get_mesh_record

Retrieve the full record for a MeSH descriptor by UI code or URI. Returns label, annotation (scope note), tree numbers, tree categories, broader descriptors, see-also cross-references, and qualifier count.

get_mesh_qualifiers

Retrieve the allowable subheading qualifiers for a descriptor (e.g. Diabetes Mellitus/therapy). Optionally includes per-qualifier indexing annotations.

get_mesh_tree

Retrieve the MeSH tree hierarchy for a descriptor: tree numbers, top-level category names, and immediate broader (parent) descriptors.


Notes on Search Behaviour

search_mesh uses left-anchored matching by default (startsWith), which matches from the beginning of the heading label. Searching diabetes will find Diabetes Mellitus and related headings, but searching mellitus will not. When a startsWith search returns no results, use match="contains" to search anywhere in the label.

For highly specialized or emerging concepts without a direct MeSH equivalent — such as specific protein families or recently coined terminology — search with a broader parent term and review the returned hierarchy to identify the best available descriptor.

Use get_mesh_record to verify before assigning. Retrieve the full record to confirm the scope note matches the intended concept, particularly when multiple candidate terms are returned. Tree numbers indicate where the term sits in the MeSH hierarchy and can guide selection of broader or narrower terms.


Installation

Requirements

  • Python 3.11 or later

  • Claude Desktop (or another MCP-compatible host)

Install from GitHub

pip install git+https://github.com/YOUR_USERNAME/mesh-mcp.git

Install from a local clone

git clone https://github.com/YOUR_USERNAME/mesh-mcp.git
cd mesh-mcp
pip install -e .

On Windows with Anaconda, use Anaconda Prompt and add --break-system-packages if prompted.


Claude Desktop Configuration

After installation, add the server to your claude_desktop_config.json. Claude Desktop uses a restricted PATH that does not include the Python bin directory, so the full path to the command is required.

To find your exact path, run the following in Terminal (Mac) or Anaconda Prompt (Windows):

  • Mac: which mesh-mcp

  • Windows: where mesh-mcp

The examples below are illustrative only — your actual path will differ depending on your Python version and installation method.

Mac (example):

{
  "mcpServers": {
    "mesh": {
      "command": "/Library/Frameworks/Python.framework/Versions/3.13/bin/mesh-mcp"
    }
  }
}

Windows/Anaconda (example):

{
  "mcpServers": {
    "mesh": {
      "command": "C:\\Users\\username\\anaconda3\\Scripts\\mesh-mcp.exe"
    }
  }
}

Always replace the path with the actual output of the which or where command on your machine.

Finding your config file:

  • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

After editing the config, quit Claude Desktop completely and reopen it. The MeSH tools will be available in your next conversation.

Verifying the installation

Once Claude Desktop is open, ask: "What cataloger tools do you have available?" — you should see all four MeSH tools listed.


Troubleshooting

Tools not appearing in Claude Desktop

  • Confirm the package installed without errors: pip show mesh-mcp

  • Confirm the command is available: mesh-mcp --help (should start the server, not throw an error)

  • Check that the config file path is correct for your OS

  • Quit Claude Desktop fully (not just close the window) before reopening

Changes to server.py not taking effect

Python caches compiled bytecode in __pycache__ folders. After editing server.py, delete any __pycache__ folders in the package directory and restart Claude Desktop fully.


Data Source

MeSH is produced by the U.S. National Library of Medicine and is freely available with no license required. Attribution is appreciated.


License

GPLv3. See LICENSE.


Development Note

The code in this project was developed in collaboration with Claude, Anthropic's AI assistant. The design decisions — including tool selection, search protocols, and the application of MeSH cataloging practice to the server's behaviour — reflect the author's professional cataloging expertise. Claude handled the implementation of those decisions in Python.


Acknowledgement

This project was inspired by and adapted from KL Tang's cataloger-mcp, extended here to apply to MeSH vocabulary lookup.

Available Tools

4 tools
get_mesh_qualifiersA

Retrieve the allowable subheading qualifiers for a MeSH descriptor.

MeSH qualifiers (subheadings) refine the topical focus of a heading — for example "Diabetes Mellitus/therapy" or "Neoplasms/diagnosis". Only qualifiers designated by NLM as allowable for the given descriptor are returned.

This is the MeSH equivalent of the maySubdivideGeographically check used in the cataloger MCP server for LCSH headings.

Note: The NLM public API does not expose qualifier abbreviations (e.g. /su for surgery). Use the full qualifier label when constructing headings in MARC: $a Diabetes Mellitus $x surgery.

Parameters

descriptor : str The MeSH UI code (e.g. "D003920") or full URI returned by search_mesh. include_annotations : bool If True, fetch each qualifier's .json record to include its indexing annotation. Makes up to 34 additional HTTP requests — use only when you need the annotation text for a specific qualifier. Default False.

Returns

dict Contains: - descriptor : The UI code queried - qualifierCount : Total number of allowable qualifiers - qualifiers : List of {label, ui, uri} dicts sorted alphabetically. If include_annotations=True, each dict also has an 'annotation' key.

ParametersJSON Schema
NameRequiredDescriptionDefault
descriptorYes
include_annotationsNo

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Excellent disclosure given no annotations exist. It explicitly warns about performance costs ('Makes up to 34 additional HTTP requests'), documents API limitations ('NLM public API does not expose qualifier abbreviations'), and details the exact return structure including optional keys, providing necessary behavioral context beyond what annotations would typically cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Structured clearly with Parameters/Returns sections. While lengthy, every sentence serves a purpose given the lack of schema documentation and output schema. The technical details (MARC formatting, HTTP request counts) are essential for correct usage, justifying the length despite the density.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Thoroughly complete for a tool with no output schema and no annotations. It documents the return dictionary structure, explains domain-specific concepts (MeSH qualifiers vs. headings), provides usage constraints, and includes practical cataloging guidance (MARC subfield construction).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage (only titles provided), the description fully compensates by documenting both parameters in detail: descriptor includes format examples ('D003920') and provenance ('returned by search_mesh'), while include_annotations explains the side effects, cost, and default value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the specific action and resource ('Retrieve the allowable subheading qualifiers for a MeSH descriptor') and distinguishes from siblings by focusing narrowly on qualifiers/subheadings versus records or trees. It clarifies the domain-specific concept with concrete examples ('Diabetes Mellitus/therapy').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear workflow context by noting the descriptor parameter can be 'returned by search_mesh', establishing a tool chain. It explicitly warns when to use the include_annotations flag ('use only when you need the annotation text'). However, it does not explicitly contrast with siblings get_mesh_record or get_mesh_tree to clarify when to prefer this tool over those alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_mesh_recordA

Retrieve a full MeSH descriptor record including scope note (annotation), tree numbers with their top-level category letters, broader descriptors, and see-also cross-references.

Use this after search_mesh to obtain cataloging details for a confirmed MeSH heading.

Parameters

descriptor : str The MeSH UI code (e.g. "D003920") or full URI returned by search_mesh.

Returns

dict A structured record containing: - ui : MeSH unique identifier (e.g. "D003920") - uri : Full RDF URI - label : Preferred heading label - annotation : Scope note / indexing annotation (if present) - dateIntroduced : Year the heading was introduced - lastUpdated : Date the record was last updated - treeNumbers : List of tree number strings (e.g. "C18.452.394.750") - treeCategories : Top-level category letters derived from tree numbers - broader : List of {label, ui} dicts for parent descriptors - seeAlso : List of {label, ui} dicts for cross-references - qualifierCount : Number of allowable qualifiers (full list via get_mesh_qualifiers)

ParametersJSON Schema
NameRequiredDescriptionDefault
descriptorYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It effectively discloses the read-only retrieval nature and comprehensively documents the return structure (ui, uri, treeNumbers, etc.). Minor gap: no mention of error handling (e.g., invalid UI codes) or rate limiting, though the data structure documentation is thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear front-loading of purpose and usage. The Returns section is lengthy, but justified given the absence of a structured output schema (Has output schema: false). The cross-references to sibling tools are efficiently integrated.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich return structure and lack of output schema/annotations, the description achieves completeness by documenting all return fields, providing parameter examples, and mapping tool relationships. Nothing critical is missing for agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Critical compensation for 0% schema coverage. The description provides exact format ('MeSH UI code'), concrete example ('D003920'), and provenance context ('returned by search_mesh'), fully explaining the parameter semantics that the schema omits.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Excellent specificity: 'Retrieve a full MeSH descriptor record' clearly states the verb and resource, and enumerates specific content included (scope note, tree numbers, broader descriptors, see-also references). The workflow distinction from search_mesh ('Use this after search_mesh') further sharpens the scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit temporal guidance ('Use this after search_mesh') establishes clear prerequisites. It also references sibling tool get_mesh_qualifiers for related functionality ('full list via get_mesh_qualifiers'), creating a clear mental model of the tool ecosystem.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_mesh_treeA

Retrieve the MeSH tree hierarchy for a descriptor: its tree numbers, the full name of each top-level category, and its immediate broader (parent) descriptors.

Use this to understand where a heading sits within the MeSH hierarchy, helping to determine whether the heading is specific enough for the work or whether a broader heading would be more appropriate.

MeSH tree number top-level categories: A Anatomy B Organisms C Diseases D Chemicals and Drugs E Analytical, Diagnostic and Therapeutic Techniques and Equipment F Psychiatry and Psychology G Phenomena and Processes H Disciplines and Occupations I Anthropology, Education, Sociology and Social Phenomena J Technology, Industry, and Agriculture K Humanities L Information Science M Named Groups N Health Care V Publication Characteristics Z Geographicals

Parameters

descriptor : str The MeSH UI code (e.g. "D003920") or full URI returned by search_mesh.

Returns

dict Contains: - ui : MeSH unique identifier - label : Preferred heading label - treeNumbers : List of tree number strings - categories : List of {letter, name} dicts for top-level categories - broader : List of {label, ui} dicts for parent descriptors

ParametersJSON Schema
NameRequiredDescriptionDefault
descriptorYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full disclosure burden. It excellently documents the return structure (ui, label, treeNumbers, categories, broader) and provides the complete MeSH category taxonomy (A-Z), which is crucial behavioral context. Lacks explicit mention of read-only/idempotent nature, though implied by 'Retrieve' and tool name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is comprehensive and well-structured with clear headers. While lengthy due to the 16-line MeSH category reference list, this domain-specific reference material earns its place by enabling the agent to interpret returned category codes. No redundant or wasted sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema and 0% input schema coverage, the description achieves completeness by documenting the full return structure (including nested object shapes) and parameter semantics. The inclusion of MeSH category mappings provides essential domain context for interpreting results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by documenting the 'descriptor' parameter with type (str), format (MeSH UI code), concrete example ('D003920'), and provenance context ('returned by search_mesh'), enabling correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states what the tool retrieves (MeSH tree hierarchy, tree numbers, top-level categories, parent descriptors) using specific verbs. It clearly distinguishes this from sibling tools by focusing on hierarchical relationships rather than searching (search_mesh) or record details (get_mesh_record).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear when-to-use guidance ('Use this to understand where a heading sits... helping to determine whether the heading is specific enough'). While it doesn't explicitly state when NOT to use it or name sibling alternatives, it implies the workflow by referencing that the descriptor parameter comes from 'search_mesh'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_meshA

Search MeSH descriptors by label using the NLM Lookup autocomplete endpoint.

Use this to find the MeSH UI code and URI for a biomedical concept before calling get_mesh_record or get_mesh_qualifiers.

Parameters

query : str The label string to search for (e.g. "diabetes", "neoplasms"). match : str Matching strategy: "startsWith" — left-anchored (default, analogous to LCSH suggest2) "contains" — substring match anywhere in the label "exact" — exact match only limit : int Maximum number of results to return (default 10, max 50).

Returns

dict A 'results' list of {label, ui, uri} dicts, or an 'error' key. 'ui' is the MeSH unique identifier (e.g. "D003920"). 'uri' is the full RDF URI (e.g. "http://id.nlm.nih.gov/mesh/D003920").

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
matchNostartsWith
limitNo

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It identifies the external endpoint ('NLM Lookup autocomplete'), documents default behaviors (startsWith matching, limit 10), and details the return structure including error handling and field definitions ('ui', 'uri'). Minor gap: does not explicitly state rate limits or timeout behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Uses a structured docstring format (Parameters/Returns sections) that efficiently organizes information. The purpose and usage guidelines are front-loaded in the first two sentences. The Returns section is necessary given the absence of an output schema, though it adds length. No redundant or tautological statements.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero schema descriptions and no output schema, the description provides comprehensive coverage: parameter semantics, return value structure, sibling relationships, and endpoint details. The inclusion of example values and URI formats (e.g., 'http://id.nlm.nih.gov/mesh/D003920') provides sufficient context for an agent to invoke the tool correctly without additional discovery.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, requiring the description to fully compensate. It excellently documents all three parameters: query includes realistic examples ('diabetes', 'neoplasms'), match explains all three enum-like options with behavioral context ('analogous to LCSH suggest2'), and limit specifies constraints ('max 50'). Completely compensates for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise action ('Search MeSH descriptors'), resource ('MeSH descriptors'), and method ('NLM Lookup autocomplete endpoint'). It clearly distinguishes itself from siblings by stating it finds codes 'before calling get_mesh_record or get_mesh_qualifiers', establishing the correct workflow sequence.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use the tool ('Use this to find the MeSH UI code and URI...') and names specific sibling alternatives to use afterwards ('before calling get_mesh_record or get_mesh_qualifiers'). This provides clear workflow guidance and prevents incorrect tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 4 tool updatesv0.1.0
    • First observedget_mesh_qualifiers
    • First observedget_mesh_record
    • First observedget_mesh_tree
    • First observedsearch_mesh

TDQS

A4.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: search_mesh finds descriptors, get_mesh_record retrieves full cataloging details, get_mesh_qualifiers fetches allowable subheadings, and get_mesh_tree provides hierarchical context. There is no functional overlap—an agent can easily distinguish when to use each tool based on the specific metadata needed.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with 'mesh' as a prefix: search_mesh, get_mesh_record, get_mesh_qualifiers, get_mesh_tree. The naming is perfectly uniform, using snake_case throughout with clear, descriptive action-object pairs.

Tool Count5/5

Four tools is well-scoped for a MeSH lookup server, covering the essential workflow: search, retrieve full record, get qualifiers, and understand hierarchy. Each tool earns its place without redundancy, and the count is appropriate for the domain's focused purpose.

Completeness5/5

The toolset provides complete coverage for MeSH descriptor lookup and cataloging support. It includes search, full record retrieval, qualifier access, and tree hierarchy—covering the entire lifecycle from discovery to detailed metadata without any obvious gaps for the server's stated purpose.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    C
    quality
    D
    maintenance
    Allows AI assistants to search the Library of Congress Subject Headings (LCSH) through a simple API interface, making it easy to query and retrieve official subject headings and related terms.
    1
    3
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    Provides AI agents with instant access to 10M+ OMOP medical vocabulary concepts for searching, mapping, and navigating clinical codes across SNOMED, ICD-10, RxNorm, LOINC, and more.
    11
    116
    6
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables Claude Desktop to search, retrieve summaries, and explore documents from an Assay document library.
    14
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/msuicaut/mesh-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server