mcp-inmovilla
A Model Context Protocol (MCP) server that provides tools to interact with the Inmovilla API. This server enables LLMs to manage properties, clients, owners, and retrieve various enumerations from the Inmovilla real estate platform.
About MCP
The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Learn more:
Installation
1. Clone and Install Dependencies
git clone <repository-url>
cd mcp-inmovilla
npm install
2. Build the Project
npm run build
3. Configure Environment Variables
Create a .env file in the project root with the following variables:
INMOVILLA_API_TOKEN=your_inmovilla_token_here
OPENAI_API_KEY=your_openai_api_key_here
Obtaining the Inmovilla API Token
To get your Inmovilla API token:
- Log in to Inmovilla CRM
- Navigate to Ajustes > Opciones > Token para API Rest
- Generate your token
- Copy the token to your
.envfile
Note: Tokens will automatically expire after 3 months of inactivity.
Obtaining the OpenAI API Key
- Sign up or log in to OpenAI Platform
- Navigate to API keys section
- Create a new API key
- Copy the key to your
.envfile
4. Start the Server
npm start
The MCP server will start on port 1337 at http://localhost:1337/mcp.
Project Structure
mcp-inmovilla/
├── src/
│ ├── tools/ # MCP Tools for Inmovilla API
│ │ ├── CreateClientTool.ts
│ │ ├── CreateOwnerTool.ts
│ │ ├── CreatePropertyTool.ts
│ │ ├── DeleteClientTool.ts
│ │ ├── DeleteOwnerTool.ts
│ │ ├── GetClientTool.ts
│ │ ├── GetEnumTool.ts
│ │ ├── GetOwnerTool.ts
│ │ ├── GetPropertyExtraInfoTool.ts
│ │ ├── GetPropertyLeadsTool.ts
│ │ ├── GetPropertyTool.ts
│ │ ├── ListPropertiesTool.ts
│ │ ├── SearchClientsTool.ts
│ │ ├── UpdateClientTool.ts
│ │ ├── UpdateOwnerTool.ts
│ │ └── UpdatePropertyTool.ts
│ └── index.ts # Server entry point
├── python_tester/ # Python client for testing
│ ├── openai2mcp_test.py # OpenAI chatbot client
│ └── requirements.txt # Python dependencies
├── package.json
├── tsconfig.json
├── .env # Environment variables (create this)
└── README.md
Python Testing Client
The python_tester folder contains a Python script that connects to the MCP server and allows you to interact with it using an OpenAI-powered chatbot.
Setup
-
Ensure the MCP server is running (see step 4 above)
-
Install Python dependencies:
cd python_tester pip install -r requirements.txt -
Run the chatbot:
python3 openai2mcp_test.py
How It Works
The Python client:
- Connects to the MCP server via Streamable HTTP on
http://localhost:1337/mcp - Uses the OpenAI API (GPT-4) to process natural language queries
- Automatically discovers and calls available MCP tools
- Provides a console-based chat interface
Example Usage
You: List all available properties
AI: [Calls list_properties tool and returns results]
You: Get information about property with reference ABC123
AI: [Calls get_property tool with the reference and returns property details]
You: What types of properties are available?
AI: [Calls get_enum tool for property types and returns the list]
Type quit or exit to end the chat session.
Available Tools
The MCP server provides the following tools for interacting with the Inmovilla API:
Properties
create_property- Create a new property or prospectget_property- Get property details by code or referenceget_property_extra_info- Get extra information (portal publication info, leads)get_property_leads- Get leads for properties within a date rangelist_properties- List all propertiesupdate_property- Update an existing property
Clients
create_client- Create a new clientget_client- Get client details by codesearch_clients- Search for clientsupdate_client- Update an existing clientdelete_client- Delete a client
Owners
create_owner- Create a new ownerget_owner- Get owner detailsupdate_owner- Update an existing ownerdelete_owner- Delete an owner
Enumerations
get_enum- Get enum values for various categories (calidades, tipos, paises, ciudades, zonas)
Development
Watch Mode
To automatically rebuild on file changes:
npm run watch
Adding New Tools
Tools are automatically loaded from the src/tools/ directory. Each tool extends the MCPTool class and defines:
name- Tool identifierdescription- What the tool doesschema- Input parameters using Zodexecute()- Tool implementation
API Documentation
For detailed information about the Inmovilla API endpoints and parameters, refer to Documentación API REST v1.html in the project root.
License
[Your License Here]