Inmovilla MCP Server

# mcp-inmovilla A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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: - [MCP Framework GitHub](https://github.com/QuantGeekDev/mcp-framework) - [MCP Framework Documentation](https://mcp-framework.com) - [MCP Specification](https://modelcontextprotocol.io) ## Installation ### 1. Clone and Install Dependencies ```bash git clone <repository-url> cd mcp-inmovilla npm install ``` ### 2. Build the Project ```bash npm run build ``` ### 3. Configure Environment Variables Create a `.env` file in the project root with the following variables: ```env 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: 1. Log in to [Inmovilla CRM](https://crm.inmovilla.com/panel) 2. Navigate to **Ajustes > Opciones > Token para API Rest** 3. Generate your token 4. Copy the token to your `.env` file > **Note**: Tokens will automatically expire after 3 months of inactivity. #### Obtaining the OpenAI API Key 1. Sign up or log in to [OpenAI Platform](https://platform.openai.com) 2. Navigate to API keys section 3. Create a new API key 4. Copy the key to your `.env` file ### 4. Start the Server ```bash 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 1. **Ensure the MCP server is running** (see step 4 above) 2. **Install Python dependencies**: ```bash cd python_tester pip install -r requirements.txt ``` 3. **Run the chatbot**: ```bash 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 prospect - `get_property` - Get property details by code or reference - `get_property_extra_info` - Get extra information (portal publication info, leads) - `get_property_leads` - Get leads for properties within a date range - `list_properties` - List all properties - `update_property` - Update an existing property ### Clients - `create_client` - Create a new client - `get_client` - Get client details by code - `search_clients` - Search for clients - `update_client` - Update an existing client - `delete_client` - Delete a client ### Owners - `create_owner` - Create a new owner - `get_owner` - Get owner details - `update_owner` - Update an existing owner - `delete_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: ```bash 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 identifier - `description` - What the tool does - `schema` - Input parameters using Zod - `execute()` - 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]