OrgLance/snomed-mcp-server

SNOMED CT MCP Server

A Model Context Protocol (MCP) server that provides access to SNOMED CT terminology services. This server can be deployed on Cloudflare Workers for scalable, serverless access to SNOMED CT data.

Features

• Search Concepts: Search for SNOMED CT concepts by term
• Concept Details: Get detailed information about specific concepts
• Descriptions: Retrieve all descriptions for a concept
• Relationships: Get concept relationships and hierarchy
• Navigation: Browse concept children and parents
• ECL Support: Search using Expression Constraint Language

Available Tools

1. search_concepts - Search for concepts by term
2. get_concept - Get concept details by ID
3. get_concept_descriptions - Get all descriptions for a concept
4. get_concept_relationships - Get concept relationships
5. get_concept_children - Get child concepts
6. get_concept_parents - Get parent concepts
7. search_by_ecl - Search using ECL expressions

Installation

Prerequisites

• Node.js 20 or later
• npm or yarn
• Claude Desktop app

Install from GitHub

1. Clone the repository:

git clone https://github.com/yourusername/snomed-mcp-server.git
cd snomed-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configure Claude Desktop

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the SNOMED MCP server to your configuration:

{
  "mcpServers": {
    "snomed-mcp-server": {
      "command": "node",
      "args": ["path/to/snomed-mcp-server/dist/index.js"]
    }
  }
}

Important: Replace path/to/snomed-mcp-server with the actual path to your cloned repository.

3. Restart Claude Desktop for the changes to take effect.

Verify Installation

After restarting Claude Desktop, you should see the following SNOMED CT tools available:

• search_concepts - Search for SNOMED CT concepts
• get_concept - Get detailed concept information
• get_concept_descriptions - Get concept descriptions
• get_concept_relationships - Get concept relationships
• get_concept_children - Get child concepts
• get_concept_parents - Get parent concepts
• search_by_ecl - Search using ECL expressions

Development

Run locally:

npm run dev

Build:

npm run build

Deployment to Cloudflare Workers

1. Install Wrangler CLI:

npm install -g wrangler

2. Login to Cloudflare:

wrangler auth login

3. Deploy:

npm run deploy

Usage Examples

Screenshot

Search for concepts

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_concepts",
    "arguments": {
      "term": "heart attack",
      "limit": 10
    }
  }
}

Get concept details

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_concept",
    "arguments": {
      "conceptId": "22298006"
    }
  }
}

Search using ECL

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_by_ecl",
    "arguments": {
      "ecl": "< 404684003",
      "limit": 20
    }
  }
}

API Endpoints

The server uses the SNOMED International public terminology server:

• Base URL: https://browser.ihtsdotools.org/snowstorm/snomed-ct/MAIN
• FHIR URL: https://snowstorm.ihtsdotools.org/fhir

Troubleshooting

MCP Server Not Appearing in Claude Desktop

1. Check Configuration File Path: Ensure you're editing the correct config file for your OS
2. Verify JSON Syntax: Make sure your claude_desktop_config.json has valid JSON syntax
3. Check File Paths: Ensure the path to dist/index.js is correct and absolute
4. Restart Required: Always restart Claude Desktop after configuration changes
5. Build First: Run npm run build before configuring Claude Desktop

Connection Issues

1. Check Build Output: Ensure dist/index.js exists after running npm run build
2. Test Locally: Run npm run dev to test the server locally
3. Node.js Version: Ensure you're using Node.js 20 or later
4. Permissions: Make sure Claude Desktop can access the file path

Common Configuration Mistakes

• Using relative paths instead of absolute paths in the configuration
• Forgetting to restart Claude Desktop after changes
• Missing the build step (npm run build)
• JSON syntax errors in the configuration file

Getting Help

If you continue to experience issues:

1. Check the Claude Desktop logs
2. Verify the server runs with npm run dev
3. Ensure all file paths are correct and accessible

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Disclaimer

This server uses the SNOMED International public terminology server for reference purposes. It is not intended for production healthcare systems. Please refer to SNOMED International licensing terms for commercial use.