Catalysis Hub MCP Server

A Model Context Protocol (MCP) server interface to Catalysis Hub's GraphQL API, enabling programmatic access to catalysis research data through flexible GraphQL queries.

Key Features

• Direct GraphQL Access: Execute any valid GraphQL query against Catalysis Hub's API
• Comprehensive Data Access:
  • Catalytic reactions (equations, conditions, catalysts)
  • Material systems (structures, properties, descriptors)
  • Research publications (titles, DOIs, authors)
  • Surface reaction data (adsorption energies, binding sites)
• MCP Standard Compliance: Implements the Model Context Protocol for AI-agent interoperability
• Flexible Query Support: Execute complex queries with variables parameterization
• Error Handling: Robust error reporting for API connectivity and query execution

Implementation Details

• Server Configuration (matches claude_desktop_config.json):

  {
    "command": "/Users/quentincody/.env/bin/python3",
    "args": ["/Users/quentincody/catalysishub-mcp-server/catalysishub_mcp_server.py"],
    "options": {
      "cwd": "/Users/quentincody/catalysishub-mcp-server"
    }
  }
  

• Core Dependency: httpx for asynchronous HTTP requests
• Transport: Standard input/output communication following MCP specifications

Setup & Installation

1. Clone the repository:

   git clone <repository_url>
   cd catalysishub-mcp-server
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Verify installation:

   python3 catalysishub_mcp_server.py --version
   # Should output: catalysishub-mcp-server 0.1.0
   

Usage Examples

Basic Query Execution

from mcp.client import MCPClient

async with MCPClient("catalysishub") as hub:
    result = await hub.catalysishub_graphql(
        query="""{
            reactions(first: 5) {
                edges {
                    node {
                        id
                        Equation
                        Temperature
                    }
                }
            }
        }"""
    )
    print(json.loads(result))

Parameterized Query with Variables

variables = {
    "materialId": "mp-1234",
    "firstResults": 5
}

response = await hub.catalysishub_graphql(
    query="""query GetMaterial($materialId: String!, $firstResults: Int!) {
        systems(uniqueId: $materialId) {
            edges {
                node {
                    energy
                    Cifdata
                    relatedReactions(first: $firstResults) {
                        edges {
                            node {
                                id
                                Equation
                            }
                        }
                    }
                }
            }
        }
    }""",
    variables=variables
)

Query Optimization Tips

1. Use GraphQL Fragments:

   fragment ReactionDetails on Reaction {
       id
       Equation
       ActivationEnergy
       Catalyst {
           formula
           surface
       }
   }
   
   query {
       reactions(first: 10) {
           edges {
               node {
                   ...ReactionDetails
               }
           }
       }
   }
   

2. Batch Related Queries:

   query BatchQuery {
       reactions: reactions(first: 5) { edges { node { id Equation } } }
       materials: systems(first: 5) { edges { node { formula energy } } }
   }
   

Response Structure

Successful responses follow this structure:

{
    "data": { /* Query results */ },
    "extensions": {
        "responseMetadata": {
            "requestDuration": 145,
            "apiVersion": "2024-06"
        }
    }
}

Error responses include detailed diagnostics:

{
    "errors": [{
        "message": "Cannot query field 'invalidField' on type 'Reaction'",
        "locations": [{"line": 5, "column": 21}],
        "path": ["query", "reactions", "edges", "node", "invalidField"]
    }]
}

Troubleshooting

Common Issues:

• HTTP Request Error: Verify network connectivity to api.catalysis-hub.org
• JSON Decode Error: Check query syntax using Catalysis Hub's GraphQL Playground
• Timeout Errors: Add timeout parameter to complex queries

License

MIT License - See LICENSE for details

Acknowledgements

This project builds on the Model Context Protocol (MCP) framework and is designed to interface with the Catalysis Hub database, a comprehensive resource for catalysis research data.