xMemory MCP Server / xMemory MCP 服务器

xMemory MCP Server 将 xMemory 的核心功能暴露为一套 AI Agent 工具，可供 Claude Desktop、Cursor、OpenCode 等使用。

The xMemory MCP Server exposes the core functionality of xMemory as a set of tools for AI agents (Claude Desktop, Cursor, OpenCode, etc.).

功能 / Features

• 记忆管理 / Memory Management: 添加、更新、删除、搜索记忆
• 知识图谱 / Knowledge Graph: 查询实体关系，探索知识网络
• 空间管理 / Space Management: 创建和管理工作空间/项目
• 文档解析 / Document Parsing: 从 PDF、DOCX、TXT、MD 文件中提取文本

配置 / Configuration

可以通过配置文件或环境变量配置 MCP 服务器。

You can configure the MCP server using a .xmemory.json config file OR environment variables.

配置文件 / Configuration File

推荐方式 / Recommended

在以下位置之一创建 .xmemory.json 文件：

Create a .xmemory.json file in one of these locations:

| 优先级 / Priority | 位置 / Location | 说明 / Notes | | ----------------- | ---------------------------------------- | ----------------------------------------------------- | | 1 | 当前工作目录 / Current working directory | 运行命令的目录 / Where you run the command | | 2 | home 目录 / Home directory | ~/.xmemory.json (Linux/Mac) | | 3 | 安装目录 / Installation dir | xmemory-mcp 安装位置 / Where xmemory-mcp is installed |

{
  "apiBaseUrl": "http://localhost:50505/api",
  "defaultSpace": "my-workspace",
  "apiKey": "xm-your-api-key-here"
}

| 字段 / Field | 必填 / Required | 说明 / Description | | -------------- | --------------- | ------------------------------------------------------------ | | apiBaseUrl | 否 / No | API 地址，默认 http://localhost:50505/api / API URL | | defaultSpace | 否 / No | 默认空间名称 / Default space name | | apiKey | 是 / Yes | xMemory 设置中的 API Key / API key from Settings > Developer |

环境变量 / Environment Variables

| 环境变量 / Env Variable | 说明 / Description | | ----------------------- | --------------------------------- | | XMEMORY_API_KEY | API 密钥 / Your API key | | DEFAULT_SPACE | 默认空间名称 / Default space name | | API_BASE_URL | API 地址 / API URL |

工具 / Tools

记忆操作 / Memory Operations

• add_memory — 添加记忆 / Add a new memory

  • content (string): 记忆内容 / The memory content
  • tags (string[]): 可选标签 / Optional tags
  • space (string): 空间名称（配置了 DEFAULT_SPACE 时可选）/ Space name
  • metadata (object): 可选元数据 / Optional metadata

• update_memory — 更新记忆 / Update an existing memory

  • id (string): 记忆 ID / Memory ID
  • content (string): 新内容 / New content
  • tags (string[]): 新标签 / New tags
  • spaceId (string): 移动到其他空间 / Move to different space

• delete_memory — 删除记忆 / Delete a memory

  • id (string): 记忆 ID / Memory ID

• search_memory — 搜索记忆 / Search for memories

  • query (string): 搜索词 / Search query
  • limit (number): 最大结果数，默认 5 / Max results
  • space (string): 按空间筛选 / Filter by space

空间操作 / Space Operations

• list_spaces — 列出所有空间 / List all spaces
• create_space — 创建空间 / Create a new space
  • name (string): 空间名称 / Space name
  • description (string): 空间描述 / Optional description
• delete_space — 删除空间（包含所有记忆）/ Delete a space and its memories
  • id (string): 空间 ID / Space ID
• get_space_details — 获取空间详情 / Get space stats
  • id (string): 空间 ID / Space ID

图谱操作 / Graph Operations

• query_graph — 查询知识图谱 / Explore the knowledge graph
  • entityName (string): 查询实体 / Look up entity
  • tag (string): 按标签筛选 / Filter by tag
  • spaceId (string): 按空间筛选 / Filter by space

工具 / Utility

• list_tags — 列出热门标签 / List popular tags
  • spaceId (string): 按空间筛选 / Optional filter
• parse_document — 解析文档 / Parse a file
  • file_path (string): 文件绝对路径 / Absolute path to file

安装 / Setup

1. 获取 API Key / Get Your API Key

1. 在浏览器中打开 xMemory / Open xMemory in your browser: http://localhost:50505
2. 进入 设置 / Settings → 开发者 / Developer
3. 点击 生成 API Key / Generate API Key 并复制

2. 安装 MCP / Install MCP

Windows:

.\scripts\install-mcp.ps1

Linux/Mac:

./scripts/install-mcp.sh

3. 配置 AI 客户端 / Configure Your AI Client

Cline / Claude Desktop:

{
  "mcpServers": {
    "xmemory-mcp": {
      "command": "xmemory-mcp"
    }
  }
}

直接配置（无需 .xmemory.json）/ Direct Configuration:

{
  "mcpServers": {
    "xmemory-mcp": {
      "command": "xmemory-mcp",
      "env": {
        "XMEMORY_API_KEY": "xm-your-api-key-here",
        "DEFAULT_SPACE": "my-workspace",
        "API_BASE_URL": "http://localhost:50505/api"
      }
    }
  }
}

OpenCode:

{
  "mcp": {
    "xmemory-mcp": {
      "type": "local",
      "command": ["xmemory-mcp"],
      "env": {
        "XMEMORY_API_KEY": "sk-xm-your-generated-key",
        "DEFAULT_SPACE": "my-workspace"
      },
      "enabled": true
    }
  }
}

注意 / Note: OpenCode 需要将环境变量放在 env 字段中。/ OpenCode requires environment variables in the env field.

故障排除 / Troubleshooting

401 Unauthorized

1. 检查 .xmemory.json 中的 apiKey 是否正确 / Check your apiKey in .xmemory.json is correct
2. 在 设置 / Settings → 开发者 / Developer 重新生成 API Key / Regenerate your API key
3. 尝试将 .xmemory.json 放在 home 目录 / Try putting .xmemory.json in your home directory

配置文件未找到 / Config Not Found

MCP 成功读取配置文件时会输出 [MCP] Loaded API key from: / The MCP will log [MCP] Loaded API key from: when it successfully reads the config file.