lucyhecht1/chariot-mcp

Chariot MCP Server

A collection (eventually:)) of tools designed to provide real-time Chariot data to LLMs through a Chariot MCP Server. These tools enhance AI conversations by enabling access to Chariot information.

For a walkthrough of the code, check out this recording: 🎥 Watch on Loom

Setup Instructions

1. Installation

   # Create and activate virtual environment
   python -m venv .venv
   source .venv/bin/activate
   
   # Install dependencies
   pip install -r requirements.txt
   
   # Install the package in editable mode
   pip install -e .
   

2. Configuration

• Create a .env file in the root directory
• Add your Chariot API credentials:

  CHARIOT_API_TOKEN=your_api_key_here
  

3. Verify Installation

   # Test if the MCP Server works
   python chariot.py
   

4. Run with Cursor
   Open Settings → Tools & Integrations in Cursor.
   You should see "chariot" listed under MCP Tools - toggle it on. It should eventually look like this:

   Heads up: You're going to need to tweak your mcp.json (and ~/.cursor/mcp.json) to make sure the paths to your Python binary and chariot.py are correct. I lean on Cursor’s own claude-3.5-sonnet agent or ask GPT to help debug. Sometimes it tells me to add from tools import org_search explicitly to our chariot.py and other times that doesn't work... One time it worked when I used mcp.tool as my decorator and other times you need mcp.tool()... I haven't been able to nail home the exact adjustment for each case, but you got this!!

Current Tools

Search Organization

Provides nonprofit organization information to LLMs during conversations by hitting the Chariot search organizations endpoint. Most importantly, it answers the question "does xx have CDA with Chariot."

Capabilities:

• Search by organization name or EIN
• Returns structured information about:
  • Name
  • Chariot Deposit Account (CDA) status
  • Location
  • EIN
  • Website
  • DAF eligibility

Example conversation:

User: "Does AFMDA have a CDA?"
LLM: *uses org_search tool*
    "Yes, American Friends of Magen David Adom (AFMDA) does have a 
     Chariot Deposit Account (CDA). They are located in New York, NY..."

Building MCP Tools

Want to extend the MCP with new tools? Here's what makes a good MCP tool:

1. Purpose

   • Provides real-time data to LLMs
   • Returns information in consistent, parseable formats
   • Enhances AI conversations with verified data

2. Structure

   • Use the @mcp.tool() decorator
   • Return formatted strings that LLMs can easily interpret
   • See org_search.py for an example

3. Best Practices

   • Keep responses concise and structured
   • Include relevant context in responses
   • Format data for natural conversation flow

Example Tool Structure

@mcp.tool()
async def my_tool(param: str) -> str:
    """
    Tool description that helps LLMs understand when to use this tool.
    
    Returns information in a consistent format:
    - Key information
    - Important details
    - Relevant context
    """
    # Implementation
    return formatted_response

Troubleshooting

If you encounter any issues:

1. Ensure Python 3.11+ is installed:

   python --version
   

2. Verify the virtual environment is activated (you should see (.venv) in your terminal prompt)

3. Confirm all dependencies are installed:

   pip list
   

4. Check that your .env file exists and contains the required API key