GovNavigator
GovNavigator - MCP Municipal Code Assistant
An MCP (Model Context Protocol) server that lets Claude search and navigate Madison, WI municipal ordinances. Ask questions like "Can I build a fence in my front yard?" and get real answers with citations!
What is MCP?
Model Context Protocol is Anthropic's open standard for connecting AI assistants to external tools and data. This project demonstrates building a production MCP server.
┌─────────────────────────────────────────────────────┐
│ Claude Desktop │
│ (asks: "fence regulations?") │
└──────────────────────┬──────────────────────────────┘
│ MCP Protocol
▼
┌─────────────────────────────────────────────────────┐
│ GovNavigator MCP Server │
│ (searches our ordinance database) │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ TF-IDF Search Index │
│ (30+ chapters of Madison city code) │
└─────────────────────────────────────────────────────┘Related MCP server: Estate Atlas SD-MCP
Features
Real Data: Scraped from Madison, WI's actual municipal code
Semantic Search: TF-IDF based search finds relevant ordinances
No API Costs: 100% free - no paid APIs needed!
Citation Support: Returns section numbers and URLs
MCP Integration: Works with Claude Desktop
Quick Start
1. Install Dependencies
# Create virtual environment
python -m venv .venv
# Activate (Windows PowerShell)
.\.venv\Scripts\Activate.ps1
# Activate (Mac/Linux)
source .venv/bin/activate
# Install dependencies
pip install -e .2. Scrape Data (Optional - data already included)
python -m src.scraper.municode_scraper3. Build Search Index
python -m src.search.index4. Configure Claude Desktop
Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"govnavigator": {
"command": "python",
"args": ["-m", "src.mcp_server.server"],
"cwd": "C:\\Users\\Krish\\OneDrive\\Desktop\\GovNavigator"
}
}
}5. Restart Claude Desktop
After adding the config, restart Claude Desktop. You should see "govnavigator" in the MCP tools list.
Example Queries
Once connected, ask Claude:
"Can I build a 6-foot fence in my front yard in Madison?"
"What are the short-term rental regulations in Madison?"
"Do I need a permit to open a food truck?"
"What are the noise ordinance quiet hours?"
"What's required for a building permit?"
Project Structure
GovNavigator/
├── src/
│ ├── scraper/ # Web scraper for Municode
│ │ └── municode_scraper.py
│ ├── search/ # TF-IDF search engine
│ │ └── index.py
│ └── mcp_server/ # MCP server implementation
│ └── server.py
├── data/
│ ├── raw/ # Scraped ordinance data
│ └── processed/ # Search index
└── pyproject.toml # Project configurationHow It Works
1. Web Scraping
Uses Playwright (browser automation) to scrape Madison's municipal code from Municode.com. Handles JavaScript-rendered content.
2. TF-IDF Search
Builds a term-frequency inverse-document-frequency index for semantic search. No AI APIs needed - pure Python math!
3. MCP Server
Exposes two tools to Claude:
search_ordinance: Search for relevant code sectionsget_ordinance_details: Get full text of a specific section
Tech Stack
Python 3.10+
MCP SDK - Anthropic's Model Context Protocol
Playwright - Browser automation for scraping
BeautifulSoup - HTML parsing
Pydantic - Data validation
Learning Resources
This project demonstrates:
Building MCP servers
Web scraping with Playwright
TF-IDF search implementation
Async Python programming
Data pipeline design
License
MIT License - Use freely for learning and building!
Built with Claude Code by a human learning AI engineering.
Available Tools
2 toolsget_ordinance_detailsA
Get full details of a specific ordinance section by title.
Use this after search_ordinance to get more details about a specific section.
Inputs: title (required).
search_ordinanceA
Search Madison, WI municipal code/ordinances for specific topics.
Use this tool when users ask about:
City regulations (fences, parking, noise, permits, etc.)
What is allowed or prohibited in Madison
Requirements for construction, businesses, animals, etc.
Penalties and fees for violations
Returns relevant ordinance sections with citations.
Examples of good queries:
"fence height limit residential"
"short term rental requirements"
"parking permit downtown"
"noise ordinance quiet hours"
"building permit required when"
Inputs: query (required), max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: search_ordinance finds relevant ordinance sections based on topics, while get_ordinance_details retrieves full details for a specific section. There is no overlap or ambiguity between them, as one is for discovery and the other for detailed lookup.
Both tools follow a consistent verb_noun pattern (search_ordinance and get_ordinance_details) with clear, descriptive names. The naming convention is uniform and predictable across the tool set.
With only two tools, the server feels thin for its apparent scope of navigating municipal codes and ordinances. While the tools cover search and detail retrieval, the lack of additional operations like listing ordinances, updating information, or handling related processes suggests an incomplete surface for the domain.
The tool set is severely incomplete for a municipal code navigation server. It only supports search and detail retrieval, missing essential operations such as listing ordinances, accessing related documents, or providing updates. This creates significant gaps that could hinder agent workflows in this domain.
Maintenance
Related MCP Connectors
Unofficial MCP server for the public PortlandMaps property/permit/zoning API. Not city-affiliated.
MCP server for querying Tulsa County, Oklahoma property and parcel data for AI agents.
An MCP server that provides congressional transcripts
MCP server giving Claude AI access to 22+ NYC public-record databases for real estate due diligence
Related MCP Servers
- AlicenseAqualityDmaintenanceOpen-source MCP server providing real estate regulatory intelligence (zoning, permits, entitlements, deal scoring) for US properties, enabling AI agents to access 10 callable tools.125 npmMIT

Estate Atlas SD-MCPofficial
AlicenseAqualityCmaintenanceMCP server for querying the San Diego Municipal Code, bulletins, permits, parcels, and zoning data with citations and freshness guarantees.14MIT- AlicenseNot gradedqualityCmaintenanceThis MCP server enables searching Korean construction standards (KDS/KCS), laws from the Ministry of Government Legislation, administrative rules and interpretations, and optionally local water/wastewater design manuals to generate grounded evidence packages for engineering answers.2MIT
- FlicenseNot gradedqualityDmaintenanceThis MCP server integrates South Korea's national law information, building registers from MOLIT, and KOSIS statistics for housing development research. It enables searching laws, retrieving building details, and accessing statistical data through natural language.-