AI导哈

PostgreSQL地理数据库AI助手

一个为PostgreSQL数据库提供AI助手接口的服务，支持PostGIS地理空间查询，允许LLM执行SQL查询、发现数据库模式并读取列描述。

  • by deltorro2
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 deltorro2/geo-post-mcp

使用说明

地理邮政mcp

MCP服务器，为PostgreSQL数据库提供人工智能辅助接口，支持PostGIS。使LLM能够执行SQL SELECT查询、运行地理空间查询、发现数据库模式和读取列描述——所有这些都可以通过 模型上下文协议.

特性

  • sql查询 --执行任何SELECT查询（JOIN、CTE、聚合、子查询）。非SELECT语句被拒绝。
  • 地理空间查询 --完全支持PostGIS。几何列返回为GeoJSON。
  • 架构发现 --列出表，用类型、可空性、默认值和空间元数据（几何类型、SRID）描述列。
  • 字段含义 --从数据库模式中读取列注释，以了解每个字段代表什么。
  • 访问控制 --可配置的允许表列表限制了可以查询哪些表。
  • 结构化日志记录 --通过structlog为每次工具调用生成JSON格式的日志。

MCP工具

工具 说明
query 执行SQL SELECT查询。返回列、行和行数。
list_tables 列出所有允许的表，并估计行数。
describe_table 描述表的列（类型、可空性、空间元数据）。
fieldmeaning 获取表的列注释/描述。

先决条件

工具 版本 目的
Python 3.11+ 运行时
PostgreSQL 14+ 数据库
PostGIS 3.0+ PostgreSQL的地理空间扩展
pip 最新 Python包管理器

自动设置

提供安装脚本来安装所有先决条件和Python依赖项。

macOS/Linux：

chmod +x install.sh
./install.sh

Windows（PowerShell作为管理员）：

.\install.ps1

手动安装

  1. Python 3.11+ — https://www.python.org/downloads/
  2. PostgreSQL 14+ — https://www.postgresql.org/download/
  3. PostGIS 3.0+ — https://postgis.net/documentation/getting_started/#installing-邮政地理信息系统
  4. 启用PostGIS 在您的数据库中：
    CREATE EXTENSION IF NOT EXISTS postgis;
  5. 安装Python依赖项：
    pip install -e .
    对于测试依赖关系：
    pip install -e ".[test]"

配置

1.设置文件

创建 geo-post-mcp-settings.json 在项目根目录中：

{
  "host": "127.0.0.1",
  "port": 5432,
  "user": "postgres",
  "dbname": "my_database",
  "schema": "public",
  "allowed_tables": ["parcels", "buildings", "roads"]
}
字段 类型 描述
host string 数据库主机
port integer 数据库端口
user string 数据库用户
dbname string 数据库名称
schema string 要查询的架构（默认值： public)
allowed_tables string[] 允许服务器访问的表

2.数据库密码

通过环境变量设置密码（从不存储在设置文件中）：

export POSTGISMCPPASS="your_password"

如果未设置，则默认为空字符串（用于无密码本地连接）。

运行服务器

使用 --sett 指定设置文件的路径。如果省略，服务器将查找 geo-post-mcp-settings.json 在当前工作目录中。

流式HTTP（用于远程访问）

fastmcp run src/server.py --transport streamable-http --host 0.0.0.0 --port 8000 -- --sett /path/to/geo-post-mcp-settings.json

stdio（适用于Claude Desktop和本地客户端）

fastmcp run src/server.py -- --sett /path/to/geo-post-mcp-settings.json

没有 --sett （在当前目录中查找）：

fastmcp run src/server.py

连接到克劳德桌面

添加到您的Claude Desktop配置文件中：

macOS: /Users/michael/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "geo-post-mcp": {
      "command": "/path/to/bin/fastmcp",
      "args": [
        "run",
        "/absolute/path/to/geo-post-mcp/src/server.py",
        "--",
        "--sett",
        "/absolute/path/to/geo-post-mcp/geo-post-mcp-settings.json"
      ],
      "env": {
        "POSTGISMCPPASS": "your_password"
      }
    }
  }
}

用实际位置替换路径。使用完整路径 fastmcp （找到它 which fastmcp).编辑后重新启动Claude Desktop。

连接到MCP检查器

本地

fastmcp dev src/server.py

这将在浏览器中打开MCP检查器 http://localhost:6274。您可以交互式地测试所有工具。

远程

在远程计算机上使用HTTP传输启动服务器：

POSTGISMCPPASS="your_password" fastmcp run src/server.py \
  --transport streamable-http --host 0.0.0.0 --port 8000

然后将MCP检查器连接到 http://<remote-host>:8000/mcp/.

运行测试

单元测试（无需数据库）

pytest -m unit

功能测试（需要数据库）

pytest -m functional

所有测试

pytest

如果数据库不可用，功能测试会自动跳过并显示一条明确的消息。

项目结构

src/
├── config/
│   ├── settings.py          # Settings loader (JSON + env var)
│   └── logging.py           # Structured logging setup
├── models/
│   ├── fieldmeaning.py      # Pydantic models for fieldmeaning tool
│   └── query.py             # QueryResult model
├── services/
│   ├── database.py          # Async database connection
│   ├── sql_validator.py     # SELECT-only enforcement
│   ├── access_control.py    # Allowed tables check
│   ├── fieldmeaning.py      # Column metadata queries
│   ├── schema.py            # Schema discovery queries
│   └── query.py             # Query execution
├── tools/
│   ├── query.py             # query MCP tool
│   ├── schema.py            # list_tables, describe_table MCP tools
│   └── fieldmeaning.py      # fieldmeaning MCP tool
└── server.py                # FastMCP server entrypoint

tests/
├── unit/                    # 48 tests, no DB required
└── functional/              # 22 tests, requires PostgreSQL+PostGIS

许可证

麻省理工学院

相关 MCP