🫁 LungMAP MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with powerful tools to access the Lung Molecular Atlas Program (LungMAP) API for lung research data discovery and analysis.

🚀 Quick Start

🎥 Demo

▶️ Watch the LungMAP MCP walkthrough

1. Clone & Install

git clone https://github.com/pankajrajdeo/lungmap-mcp-server.git
cd lungmap-mcp-server
pip install -e .

2. Test the Server

python scripts/test_server.py

3. Use with Claude Desktop

Add to your Claude Desktop config:

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

{
  "mcpServers": {
    "lungmap": {
      "command": "python3",
      "args": ["/absolute/path/to/lungmap_mcp_server.py"]
    }
  }
}

🛠️ Features

🔍 8 Powerful Research Tools

Tool	Purpose	Use Case
search_datasets	Primary discovery tool	Find datasets, genes, analysis entities
get_dataset_details	Comprehensive dataset info	Deep dive into specific datasets
get_sample_details	Sample metadata	Donor information and demographics
get_analysis_results	Computational results	Gene lists and statistical analyses
get_molecular_entities	Gene sets & ontology	Gene sets, probes, anatomy terms
get_infrastructure_resources	Research infrastructure	Researchers, sites, technologies
list_controlled_vocabulary	Filter validation	Discover valid search parameters
search_media	Files & images	Find protocols, histology images

🎯 3 Workflow Prompts

• search_workflow - Dataset discovery guidance
• analysis_workflow - Data analysis workflow
• discovery_workflow - Exploratory research tips

📚 2 Resource Endpoints

• lungmap://api/base_url - API base URL reference
• lungmap://api/documentation - Complete API documentation

💡 Usage Examples (MCP)

Below are examples that use the MCP protocol. Tools are executed via an MCP client, not by importing Python functions directly.

1) Using Claude Desktop (No code)

• Add the server in Claude Desktop config (see Quick Start)
• Then ask natural language queries like:
  • "Find human RNA-seq datasets about lung development"
  • "Get details for dataset LMEX0000000661 including files and images"
  • "Search everything about ACE2"

Claude will call the MCP tools (e.g., search_datasets, get_dataset_details) behind the scenes.

2) Using the MCP Python Client (stdio)

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="python3",
        args=["/absolute/path/to/lungmap_mcp_server.py"],
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the session
            await session.initialize()

            # Call a tool: search_datasets
            result = await session.call_tool(
                "search_datasets",
                arguments={
                    "text_query": "lung development",
                    "species": "human",
                    "dataset_types": ["rna_seq"],
                    "limit": 5,
                },
            )
            print(result.content)

            # Call a tool: get_dataset_details
            details = await session.call_tool(
                "get_dataset_details",
                arguments={
                    "dataset_id": "LMEX0000000661",
                    "include_files": True,
                    "include_images": True,
                    "include_resources": True,
                },
            )
            print(details.content)

asyncio.run(main())

3) Using LangChain MCP Adapters

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from langchain_mcp_adapters.tools import load_mcp_tools
from langgraph.prebuilt import create_react_agent

async def main():
    server_params = StdioServerParameters(
        command="python3",
        args=["/absolute/path/to/lungmap_mcp_server.py"],
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Load all MCP tools as LangChain tools
            tools = await load_mcp_tools(session)

            # Create a ReAct agent and invoke it
            agent = create_react_agent("openai:gpt-4o-mini", tools)
            response = await agent.ainvoke({
                "messages": [{"role": "user", "content": "Search everything about ACE2"}]
            })
            print(response)

asyncio.run(main())

📁 Project Structure

lungmap-mcp-server/
├── 📄 README.md                    # This file
├── 📄 LICENSE                      # MIT License
├── 📄 pyproject.toml               # Python package config
├── 📄 lungmap_mcp_server.py        # Main MCP server
├── 📁 docs/                        # Documentation
│   ├── 📄 quickstart.md            # 5-minute setup guide
│   ├── 📄 installation_guide.md    # Detailed installation
│   ├── 📄 deployment_checklist.md  # Production checklist
│   └── 📄 mcp_config_examples.json # Configuration examples
├── 📁 scripts/                     # Utility scripts
│   ├── 🔧 setup_script.sh          # Automated setup
│   └── 🧪 test_server.py           # Server testing
├── 📁 tests/                       # Test suite
│   └── 🧪 test_tools.py            # Tool tests
└── 📁 tools/                       # Tool implementations
    ├── 📄 api_client.py            # API client utilities
    ├── 📄 constants.py             # Constants & mappings
    ├── 📄 types.py                 # Type definitions
    └── 📄 [8 lungmap tools].py     # Individual tools

🔧 Installation

Prerequisites

• Python 3.10+
• pip or uv package manager

Option 1: Quick Install

git clone https://github.com/pankajrajdeo/lungmap-mcp-server.git
cd lungmap-mcp-server
pip install -e .

Option 2: With Virtual Environment

git clone https://github.com/pankajrajdeo/lungmap-mcp-server.git
cd lungmap-mcp-server
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e .

Option 3: Using uv (Faster)

git clone https://github.com/pankajrajdeo/lungmap-mcp-server.git
cd lungmap-mcp-server
uv venv
source .venv/bin/activate
uv pip install -e .

🧪 Testing

# Test server functionality
python scripts/test_server.py

# Test individual tools
python tests/test_tools.py

# Run with pytest (if installed)
pytest tests/

🔗 Integration

Claude Desktop

See Claude Desktop Setup Guide

LangChain/LangGraph

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from langchain_mcp_adapters.tools import load_mcp_tools

server_params = StdioServerParameters(
    command="python3",
    args=["/path/to/lungmap_mcp_server.py"],
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await load_mcp_tools(session)
        # Use tools with your LangChain agent

📊 API Reference

🌐 Remote Deployment & Auth

Environment variables:

# Transport
MCP_TRANSPORT=sse   # or stdio
HOST=0.0.0.0
PORT=8000
MCP_SSE_PATH=/sse

# Auth (optional but recommended for SSE)
LUNGMAP_MCP_TOKEN=your-secret-token

# Rate limiting
MAX_REQUESTS_PER_MINUTE=60

Run with SSE locally:

MCP_TRANSPORT=sse PORT=8000 LUNGMAP_MCP_TOKEN=dev-token \
python lungmap_mcp_server.py

Health/resource checks via MCP client:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# For SSE, use appropriate client/URL; below shows stdio example

Security & limits:

• Bearer token required if LUNGMAP_MCP_TOKEN set.
• Per-tool rate limit defaults to 60 req/min; configure via env.
• Responses soft-capped at ~100KB; narrow queries or reduce limits if exceeded.

🤝 Connect Clients (ChatGPT, Claude, Cursor)

ChatGPT (MCP over SSE)

1. Start server with SSE and token (see above)

2. Use the OpenAI Responses API with MCP tools (example):

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "o4-mini",
    "input": "Find human RNA-seq datasets about lung development",
    "tools": [{
      "type": "mcp",
      "server_label": "lungmap",
      "server_url": "http://localhost:8000/sse",
      "allowed_tools": ["search", "search_datasets", "get_dataset_details", "get_sample_details", "get_analysis_results", "get_molecular_entities", "get_infrastructure_resources", "list_controlled_vocabulary", "search_media", "fetch"],
      "require_approval": "never",
      "metadata": {
        "headers": {"Authorization": "Bearer dev-token"}
      }
    }]
  }'

Notes:

• search/fetch are provided for generic connectors; domain tools are also available.
• Pass the same Bearer token via metadata.headers.Authorization.

Claude Desktop (Remote via @modelcontextprotocol/client)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "lungmap-remote": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/client", "http://localhost:8000/sse"],
      "env": {
        "AUTHORIZATION": "Bearer dev-token"
      }
    }
  }
}

Then restart Claude Desktop and verify the MCP server is connected.

Cursor / Local stdio

Add a local stdio server entry in your settings or run:

python lungmap_mcp_server.py   # stdio mode

Use the domain tools directly (e.g., search_datasets) from your agent.

🧪 Testing (stdio & SSE)

• Stdio test:

python scripts/test_server.py

• SSE integration tests (optional):

MCP_TRANSPORT=sse PORT=8000 LUNGMAP_MCP_TOKEN=dev-token \
python lungmap_mcp_server.py &

TEST_SSE_BASE=http://localhost:8000 pytest -q tests/test_remote.py

Base URL

https://www.lungmap.net/api

ID Formats

• Datasets: LMEX* (e.g., LMEX0000000661)
• Samples: LMSP* (e.g., LMSP0000001176)
• Analyses: LMAN* (e.g., LMAN0000000037)
• Researchers: LMRS* (e.g., LMRS0000000174)
• Sites: LMSI* (e.g., LMSI0000000026)

Common Filters

• Species: human, mouse
• Dataset Types: rna_seq, proteomics, imaging, single_cell, atac_seq, chip_seq
• Age Ranges: prenatal, newborn, infant, child, adolescent, adult, elderly
• Sex: male, female, unknown

🐛 Troubleshooting

Common Issues

❌ Import Errors

# Ensure you're in the project directory
cd lungmap-mcp-server
pip install -e .

❌ Server Won't Start

# Check Python version
python3 --version  # Must be 3.10+

# Test server manually
python lungmap_mcp_server.py

❌ Claude Desktop Not Connecting

• Use absolute paths in config
• Restart Claude Desktop completely
• Check Claude Desktop logs

Getting Help

• 🐛 Bug Reports: Open an issue
• 💡 Feature Requests: Start a discussion
• 📚 LungMAP API: Official Documentation
• 🔧 MCP Protocol: MCP Documentation

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

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

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• LungMAP Consortium for providing the comprehensive lung research API
• Anthropic for the Model Context Protocol specification
• Open Source Community for the tools and libraries that made this possible

📖 About LungMAP

The Lung Molecular Atlas Program (LungMAP) is an NHLBI-funded consortium focused on understanding lung development and disease through molecular profiling. Learn more at lungmap.net.

---

⭐ Star this repository if you find it useful!