seema469/civiclens-mcp

🏡 Civiclens MCP Server

Civiclens is a Model Context Protocol (MCP) server that helps AI assistants or apps find and summarize government/public assistance programs (e.g., housing, rental, and other benefits).

It uses:

Serper.dev → Google Search API for up-to-date results

OpenAI GPT-4o-mini → Summarization into structured JSON + Markdown

This project demonstrates building a fully working MCP server with tools for Claude Desktop, MCP Inspector, or future ChatGPT MCP integrations.

✨ Features

🔍 Search .gov sites for relevant assistance programs

📝 Summarize results into structured JSON and Markdown reports

⚡ Run as a local MCP server (no separate hosting needed)

🧩 Works in MCP Inspector for easy testing

💾 Automatically saves Markdown summaries in a reports/ folder

🚀 Quick Start

1. Clone and Install git clone https://github.com/seema469/civiclens-mcp.git cd civiclens-mcp python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e .

2. Set API Keys

This project requires:

Serper API Key: Get it here

OpenAI API Key: Get it here

Set keys in your shell:

export SERPER_API_KEY=sk-xxxx export OPENAI_API_KEY=sk-xxxx

3. Run the Server civiclens-mcp

If installed correctly, it will start and wait for MCP clients.

4. Test with MCP Inspector

Install Inspector:

npm install -g @modelcontextprotocol/inspector mcp-inspector

Configure in Inspector UI:

Transport Type STDIO Command python Arguments /full/path/to/.venv/bin/civiclens-mcp Environment Vars SERPER_API_KEY, OPENAI_API_KEY

Click Connect → You’ll see these tools:

search_public_schemes

summarize_schemes

find_and_summarize_schemes

5. Example Query

Run find_and_summarize_schemes with:

{ "query": "California housing assistance program", "num": 5 }

Output fields:

summary: AI-written summary

programs: Structured JSON of programs

markdown: Formatted Markdown string

markdown_file: Path to a saved .md report in reports/

📂 Project Structure civiclens-mcp/ ├─ civiclens_mcp/ │ ├─ init.py │ ├─ server.py # MCP server entry point │ ├─ tools.py # All tool logic ├─ reports/ # Generated Markdown summaries ├─ pyproject.toml # Project metadata and scripts ├─ README.md └─ LICENSE

🧩 Tools Tool Description search_public_schemes Uses Serper API to find matching programs summarize_schemes Summarizes search results into JSON & text find_and_summarize_schemes One-shot search + summarization + Markdown 📝 Example Markdown Output

🏡 Summary for Query: California housing assistance program

🔍 Summary

California offers multiple housing support programs including CalWORKs Housing Support and emergency rental assistance.

📋 Programs

🔗 Raw Search Results

• California Housing Assistance Programs — Find rental, mortgage, and utility assistance programs...
• CalWORKs Housing Support Program — Helps homeless families secure and maintain housing...

🛠️ Development

Reinstall your package in editable mode after changes:

pip install -e .

Run tests in MCP Inspector or Claude Desktop Pro.

📜 License

MIT License

📸 Screenshots