Tar-ive/grants-mcp

Grants MCP Server

A Model Context Protocol (MCP) server for comprehensive government grants discovery and analysis, powered by the Simpler Grants API.

Overview

The Grants MCP Server is a Python-based MCP implementation using FastMCP that provides intelligent tools for discovering, analyzing, and tracking government grant opportunities. It offers multiple specialized tools for different aspects of grant research, from opportunity discovery to funding trend analysis and agency landscape mapping.

Features

🔍 Core Capabilities

• Grant Opportunity Discovery: Search and filter grants based on keywords, agencies, funding categories, and eligibility criteria
• Funding Trend Analysis: Analyze historical funding patterns and identify emerging opportunities
• Agency Landscape Mapping: Understand the grant ecosystem across different government agencies
• Intelligent Caching: Built-in caching system to optimize API calls and improve response times
• Comprehensive Grant Details: Access detailed information including funding amounts, deadlines, eligibility requirements, and contact information

🛠️ Technical Features

• Built with FastMCP for robust MCP server implementation
• Asynchronous Python architecture for high performance
• Dual Transport Support: stdio (local) and HTTP (containerized)
• Docker Support: Ready-to-deploy containerized version
• Configurable caching with TTL and size limits
• Retry logic and error handling for API resilience
• Environment-based configuration management
• Comprehensive test suite with unit, integration, and live tests

Quick Start with Docker 🐳

Prerequisites

• Docker and Docker Compose installed
• Simpler Grants API key (see Obtaining API Key)

1. Clone the Repository

git clone https://github.com/Tar-ive/grants-mcp.git
cd grants-mcp

2. Configure API Key

Important: You must provide your own API key. Never commit API keys to version control.

Option A - Using .env file (Recommended):

# Copy the example file
cp .env.example .env

# Edit .env and add your actual API key
# SIMPLER_GRANTS_API_KEY=your_actual_api_key_here

Option B - Edit docker-compose.yml directly:

environment:
  - SIMPLER_GRANTS_API_KEY=your_actual_api_key_here

3. Build and Run

# Build the Docker image
docker-compose build

# Start the container
docker-compose up -d

# Check if it's running
docker ps | grep grants-mcp

# View logs
docker logs grants-mcp-server

4. Test the Server

# Test with curl
curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Or use the provided test script
python scripts/test_http_local.py

5. Configure Claude Desktop

Copy the Docker configuration to Claude Desktop:

# For macOS
cp claude_desktop_configs/config_local_docker.json \
   ~/Library/Application\ Support/Claude/claude_desktop_config.json

# For Windows
cp claude_desktop_configs/config_local_docker.json \
   %APPDATA%\Claude\claude_desktop_config.json

Then restart Claude Desktop to connect to your containerized MCP server.

Architecture

grants-mcp/
├── src/
│   └── mcp_server/
│       ├── server.py              # Main server implementation
│       ├── config/                # Configuration management
│       │   └── settings.py
│       ├── models/                # Data models and schemas
│       │   └── grants_schemas.py
│       ├── tools/
│       │   ├── discovery/         # Grant discovery tools
│       │   │   ├── opportunity_discovery_tool.py
│       │   │   ├── agency_landscape_tool.py
│       │   │   └── funding_trend_scanner_tool.py
│       │   └── utils/             # Utility modules
│       │       ├── api_client.py
│       │       ├── cache_manager.py
│       │       └── cache_utils.py
│       └── prompts/               # System prompts
├── scripts/                       # Testing and deployment scripts
│   ├── test_http_local.py       # Test HTTP endpoint
│   ├── test_http_no_docker.py   # Run HTTP server locally
│   └── debug_connection.sh      # Debug connectivity
├── claude_desktop_configs/        # Claude Desktop configurations
│   ├── config_local_stdio.json  # Direct Python execution
│   ├── config_local_docker.json # Docker via mcp-remote
│   └── config_both.json         # Both options
├── docker-compose.yml            # Docker Compose configuration
├── Dockerfile                    # Container definition
└── tests/                        # Comprehensive test suite

Deployment Options

Option 1: Docker (Recommended for Production)

The Docker deployment provides:

• Consistent environment across platforms
• Easy scaling and deployment
• Isolation from system dependencies
• Ready for cloud deployment (Google Cloud Run, AWS ECS, etc.)

# Quick start
docker-compose up -d

# Stop the server
docker-compose down

# View logs
docker logs grants-mcp-server --follow

# Rebuild after code changes
docker-compose build && docker-compose up -d

Option 2: Local Python Installation

For development and testing:

# Install dependencies
pip install -r requirements.txt

# Run with stdio transport (for direct integration)
SIMPLER_GRANTS_API_KEY=your_key python main.py

# Run with HTTP transport (for testing containerization locally)
MCP_TRANSPORT=http PORT=8080 SIMPLER_GRANTS_API_KEY=your_key python main.py

Obtaining API Key

The Simpler Grants API key is required for this MCP server to function. To get your API key:

1. Visit Simpler Grants API
2. Sign up for an account or log in
3. Navigate to your API settings/dashboard
4. Generate or copy your API key
5. Keep this key secure - you'll need it for configuration

Configuration

Environment Variables

Docker Configuration

The docker-compose.yml file includes:

• Port mapping: 8081 (host) → 8080 (container)
• Resource limits: 1 CPU, 1GB RAM
• Auto-restart policy
• Health checks with proper SSE headers

Available Tools

1. opportunity_discovery

Search for grant opportunities with detailed analysis.

Parameters:

• query: Search keywords (e.g., "renewable energy", "climate change")
• filters: Advanced filter parameters
• max_results: Maximum number of results (default: 100)
• page: Page number for pagination
• grants_per_page: Grants per page (default: 3)

2. agency_landscape

Map agencies and their funding focus areas.

Parameters:

• include_opportunities: Include opportunity analysis (default: true)
• focus_agencies: Specific agency codes (e.g., ["NSF", "NIH"])
• funding_category: Filter by category
• max_agencies: Maximum agencies to analyze (default: 10)

3. funding_trend_scanner

Analyze funding trends and patterns.

Parameters:

• time_window_days: Analysis period (default: 90)
• category_filter: Filter by category
• agency_filter: Filter by agency
• min_award_amount: Minimum award filter
• include_forecasted: Include forecasted opportunities (default: true)

Claude Desktop Integration

For Docker Deployment

1. Ensure Docker container is running: docker-compose up -d
2. Install mcp-remote if needed: npm install -g mcp-remote
3. Copy configuration:

   # macOS
   cp claude_desktop_configs/config_local_docker.json \
      ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

4. Restart Claude Desktop

For Local Development

1. Copy the stdio configuration:

   # macOS
   cp claude_desktop_configs/config_local_stdio.json \
      ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. Update the path in the config to your local installation
3. Restart Claude Desktop

Testing

Test Docker Deployment

# Run test script
python scripts/test_http_local.py

# Debug connection issues
bash scripts/debug_connection.sh

# Manual test with curl
curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Run Test Suite

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test categories
pytest tests/unit/
pytest tests/integration/
pytest tests/live/  # Requires API key

Troubleshooting

Port Conflicts

If port 8081 is in use:

# Check what's using the port
lsof -i :8081

# Edit docker-compose.yml to use a different port
# Change "8081:8080" to "8082:8080"

Container Issues

# Check container status
docker ps -a | grep grants-mcp

# View detailed logs
docker logs grants-mcp-server --tail 100

# Restart container
docker-compose restart

# Rebuild from scratch
docker-compose down
docker-compose build --no-cache
docker-compose up -d

API Key Issues

• Ensure SIMPLER_GRANTS_API_KEY is set in docker-compose.yml
• Check logs for authentication errors: docker logs grants-mcp-server
• Verify API key is valid at Simpler Grants API

Cloud Deployment

The containerized version is ready for cloud deployment:

Google Cloud Run

# Build and push to Google Container Registry
gcloud builds submit --tag gcr.io/YOUR_PROJECT/grants-mcp

# Deploy to Cloud Run
gcloud run deploy grants-mcp \
  --image gcr.io/YOUR_PROJECT/grants-mcp \
  --platform managed \
  --port 8080 \
  --set-env-vars SIMPLER_GRANTS_API_KEY=your_key

AWS ECS / Fargate

See specs/cloud_deployment.md for detailed AWS deployment instructions.

Development

Project Structure

• src/mcp_server/: Core server implementation
• scripts/: Testing and utility scripts
• tests/: Comprehensive test suite
• specs/: Technical specifications and documentation
• claude_desktop_configs/: Ready-to-use Claude Desktop configurations

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes and add tests
4. Ensure tests pass: pytest
5. Build and test Docker image: docker-compose build && docker-compose up -d
6. Commit with descriptive messages
7. Push and create a pull request

Roadmap

• Phase 1: Python implementation with FastMCP
• Phase 2: Enhanced discovery tools
• Phase 3: Docker containerization
• Phase 4: Intelligent scoring system
• Phase 5: Cloud deployment automation
• Phase 6: Multi-agency comparison tools
• Phase 7: Grant application assistance

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with FastMCP
• Powered by Simpler Grants API
• Model Context Protocol by Anthropic

Support

For issues, questions, or contributions:

• Open an issue on GitHub
• Check the for detailed instructions
• Review specs/ directory for technical documentation

Note: This is an alpha release. API and features may change. Use in production with caution.# Deployment Test

Service accounts and permissions are now properly configured!