Booli MCP Server
A Model Context Protocol (MCP) server for accessing Swedish real estate data from Booli.se through GraphQL API. This server enables AI assistants to search and analyze property listings using natural language queries.
Features
- Property Search: Search for apartments and houses with comprehensive filtering options
- Location Discovery: Find area IDs and location names for targeted property searches
- Natural Language Queries: AI assistants can interpret conversational property requests
- GraphQL Integration: Efficient API communication with Booli's GraphQL endpoint
- Structured Responses: Returns property data in standardized format with rich text formatting
Installation
npm install
npm run build
Configuration
- Copy the environment template:
cp .env.example .env
- Set the Booli GraphQL endpoint in
.env:
BOOLI_GRAPHQL_URL=https://api.booli.se/graphql
Usage
Development
npm run dev
Production
npm start
With Claude Desktop
Add to your Claude Desktop MCP configuration:
{
"mcpServers": {
"booli": {
"command": "node",
"args": ["/path/to/booli-mcp-server/dist/index.js"],
"env": {
"BOOLI_GRAPHQL_URL": "https://api.booli.se/graphql"
}
}
}
}
Available Tools
search_locations
Find location suggestions and area IDs for property searches:
query(string, required): Search query to find location suggestions (e.g., "ektorp", "stockholm", "nacka")limit(number, optional): Maximum results to return (default: 10)
Example usage: Use this tool first to discover location IDs, then use those IDs in property searches for more targeted results.
search_properties
Search for properties with comprehensive filtering options:
Basic Parameters:
location(string): Location to search (area ID or name, e.g., "Stockholm", "509")minPrice(number): Minimum price in SEKmaxPrice(number): Maximum price in SEKminRooms(number): Minimum number of roomsmaxRooms(number): Maximum number of roomsminArea(number): Minimum living area in m²maxArea(number): Maximum living area in m²propertyType(string): "apartment" or "house"
Advanced Parameters:
minPricePerSqm(number): Minimum price per square metermaxPricePerSqm(number): Maximum price per square meterminPlotArea(number): Minimum plot area for housesmaxPlotArea(number): Maximum plot area for housesminConstructionYear(number): Minimum construction yearmaxConstructionYear(number): Maximum construction yearmaxRent(number): Maximum monthly rent for cooperativesdaysActive(number): Maximum days listing has been activeamenities(string): Comma-separated amenities listfloor(string): "bottomFloor" or "topFloor"showOnly(string): Special filters (e.g., "priceDecrease,newConstruction")limit(number): Maximum results to return (default: 10)
Example Queries
Location Discovery:
- "Find locations matching 'ektorp'"
- "Search for areas in Stockholm"
- "What locations are available in Nacka?"
Property Search:
- "Show me 2-bedroom apartments under 4M SEK in Stockholm"
- "Find houses in Göteborg with at least 100m² living area"
- "Search for properties in Södermalm between 2-5M SEK"
- "Find apartments in area 509 with balcony"
Combined Workflow:
- First: "Find locations matching 'södermalm'"
- Then: "Search properties in area 123 with 2-3 rooms under 5M SEK"
Development
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm test
# Type checking
npm run typecheck
# Linting
npm run lint
# Start development server
npm run dev
Testing
The project includes comprehensive test coverage:
# Run all tests
npm test
# Run specific test files
npm test tests/location-types.test.ts
npm test tests/types.test.ts
# Run tests with coverage
npm run test:coverage
Test coverage includes:
- Type validation with Zod schemas
- GraphQL client functionality
- MCP tool implementations
- Error handling and edge cases
- Integration tests with real API calls
License
MIT