使用说明

读取MCP服务器

基于Go的模型上下文协议（MCP）服务器，允许AI助手访问您的睿读亮点和读者图书馆。

服务器充当无状态代理：客户端在每个请求中传递Readwise API密钥，服务器将其转发给Readwise API。没有存储凭据。

特性

29个MCP工具 涵盖亮点、文档、标签、视频和搜索
档案系统 控制哪些工具暴露在外
本机TLS 具有双侦听器模式（MCP为HTTPS，健康探测为HTTP）
内存LRU缓存 具有按用户隔离和自动失效功能
分散容器映像 最小攻击面
Kubernetes就绪 具有健康/准备就绪探针和VPA支持

快速开始

与波德曼一起跑步

# Build the container image
podman build -t readwise-mcp-server -f Containerfile .

# Run with default settings (readwise profile, no TLS)
podman run -p 8080:8080 readwise-mcp-server

# Run with multiple profiles
podman run -p 8080:8080 \
  -e READWISE_PROFILES=basic \
  readwise-mcp-server

从源代码构建

make build
READWISE_PROFILES=basic ./build/readwise-mcp-server

客户端配置

将MCP客户端指向服务器 /mcp 端点，在中传递Readwise API密钥 Authorization 头球

克劳德代码 (~/.claude/settings.json):

{
  "mcpServers": {
    "readwise": {
      "type": "streamable-http",
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Token YOUR_READWISE_API_KEY"
      }
    }
  }
}

获取API密钥： readwise.io/access_token.

档案

配置文件控制服务器公开哪些工具。通过设置 READWISE_PROFILES 环境变量以逗号分隔的列表形式显示。

基础配置文件

配置文件	类型	工具	依赖关系
`readwise`	阅读用于Readwise突出显示API（v2）的	9工具	无
`reader`	阅读	4个用于阅读器文档的工具API（v3）	none
`write`	修饰符	7个用于创建/更新内容的工具	`readwise` 或 `reader`
`video`	modifier	用于视频文档和播放的5个工具	`reader`
`destructive`	修饰符	4个用于删除内容的工具	`readwise` 或 `reader`

捷径

快捷方式	展开为
`basic`	`reader`, `write`
`all`	`readwise`, `reader`, `write`, `video`, `destructive`

配置文件示例

# Default: only Readwise highlights (read-only)
READWISE_PROFILES=readwise

# Reader with write access (same as "basic")
READWISE_PROFILES=reader,write

# Everything except destructive operations
READWISE_PROFILES=readwise,reader,write,video

# All tools enabled
READWISE_PROFILES=all

启动时验证依赖关系。如果启用了修改器配置文件而没有其所需的读取配置文件（例如。， write 没有 readwise 或 reader).

工具

Readwise Profile（9个工具）

工具	说明
`list_sources`	列出突出显示的来源（书籍、文章等），并进行分页和过滤
`get_source`	按ID获取单个源的详细信息
`list_highlights`	使用分页和过滤功能列出突出显示
`get_highlight`	按ID获取单个突出显示
`export_highlights`	批量导出按来源分组的所有亮点
`get_daily_review`	获取今天的每日回顾亮点
`list_source_tags`	列出特定源上的所有标签
`list_highlight_tags`	列出特定突出显示的所有标签
`search_highlights`	按文本、注释和标题的查询搜索突出显示

读者档案（4个工具）

工具	说明
`list_documents`	按位置/类别筛选列出阅读器文档
`get_document`	获取单个文档，可选择包含完整内容
`list_reader_tags`	列出阅读器中的所有标签
`search_documents`	在标题、作者、摘要和注释中搜索文档

写个人资料（7个工具）

工具	说明
`save_document`	将URL保存到阅读器
`update_document`	更新文档元数据（标题、作者、摘要、位置、标签）
`create_highlight`	在源上创建新的突出显示
`update_highlight`	更新现有突出显示的文本、注释、位置或颜色
`add_source_tag`	向源添加标签
`add_highlight_tag`	在突出显示中添加标签
`bulk_create_highlights`	在单个请求中创建多个突出显示

视频配置文件（5个工具）

工具	说明
`list_videos`	列出阅读器中的视频文档
`get_video`	获取带有成绩单的视频文档
`get_video_position`	获取当前播放位置
`update_video_position`	更新播放位置（需要 `write`)
`create_video_highlight`	在视频上创建带时间戳的亮点（需要 `write`)

破坏性轮廓（4个工具）

工具	说明
`delete_highlight`	永久删除突出显示
`delete_highlight_tag`	从突出显示中删除标签
`delete_source_tag`	从源中删除标签
`delete_document`	永久删除阅读器文档

配置

所有配置都是通过环境变量进行的。

变量	默认值	描述
`READWISE_PROFILES`	`readwise`	逗号分隔的配置文件名称
`PORT`	`8080`	HTTP端口（健康探测，或TLS关闭时的MCP）
`TLS_CERT_FILE`		TLS证书PEM文件的路径
`TLS_KEY_FILE`		TLS私钥PEM文件的路径
`TLS_PORT`	`8443`	MCP端点的HTTPS端口（当TLS打开时）
`LOG_LEVEL`	`info`	日志级别： `debug`, `info`, `warn`, `error`
`CACHE_ENABLED`	`true`	启用内存中的响应缓存
`CACHE_MAX_SIZE_MB`	`128`	最大缓存大小（MB）
`CACHE_TTL_SECONDS`	`300`	默认缓存TTL（秒）

传输层安全

服务器支持具有双侦听器架构的本机TLS：

超文本传输安全协议 上 TLS_PORT （默认8443）：提供 /mcp 端点
超文本传输协议 上 PORT （默认8080）：服务 /health 和 /ready 探针

这使得Kubernetes可以在加密MCP流量的同时通过普通HTTP探测容器。

启用TLS

设置两者 TLS_CERT_FILE 和 TLS_KEY_FILE服务器验证这两个文件是否存在并且可读，以及 TLS_PORT 不同于 PORT.

podman run -p 8080:8080 -p 8443:8443 \
  -v ./certs:/etc/tls:ro \
  -e TLS_CERT_FILE=/etc/tls/tls.crt \
  -e TLS_KEY_FILE=/etc/tls/tls.key \
  -e READWISE_PROFILES=basic \
  readwise-mcp-server

当未配置TLS时，所有端点都通过HTTP在 PORT.

健康终点

端点	端口	描述
`/health`	HTTP	Liveness探测，总是返回200
`/ready`	HTTP	就绪探测，总是返回200
`/mcp`	HTTPS（或HTTP）	MCP协议端点

缓存

服务器缓存每个用户的API响应（由API密钥的散列键控），并执行LRU逐出。

导出和列出端点使用5分钟TTL
标签列表使用10分钟TTL
写入和删除操作会自动使受影响的缓存条目无效
禁用缓存 CACHE_ENABLED=false

在Kubernetes上部署

以下示例将服务器部署为Kubernetes集群上具有本机TLS的StatefulSet。

生成TLS证书

openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout tls.key -out tls.crt \
  -subj "/CN=mcp-readwise.example.com" \
  -addext "subjectAltName=DNS:mcp-readwise.example.com,IP:10.0.0.100"

创建TLS密钥

使用kustomize秘密生成器或直接创建秘密：

# auth/kustomization.yml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

secretGenerator:
- name: readwise-mcp-tls
  type: kubernetes.io/tls
  files:
  - tls.crt
  - tls.key

generatorOptions:
  disableNameSuffixHash: true

状态集和服务

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: readwise-mcp
spec:
  replicas: 1
  serviceName: readwise-mcp-pods
  selector:
    matchLabels:
      app: readwise-mcp
  template:
    metadata:
      labels:
        app: readwise-mcp
    spec:
      containers:
      - name: mcp
        image: readwise-mcp-server:latest
        ports:
        - name: http
          containerPort: 8080
        - name: https
          containerPort: 8443
        env:
        - name: READWISE_PROFILES
          value: "basic"
        - name: PORT
          value: "8080"
        - name: TLS_CERT_FILE
          value: "/etc/tls/tls.crt"
        - name: TLS_KEY_FILE
          value: "/etc/tls/tls.key"
        - name: TLS_PORT
          value: "8443"
        - name: LOG_LEVEL
          value: "info"
        - name: CACHE_ENABLED
          value: "true"
        volumeMounts:
        - name: tls-certs
          mountPath: /etc/tls
          readOnly: true
        livenessProbe:
          httpGet:
            path: /health
            port: http
          initialDelaySeconds: 5
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /ready
            port: http
          initialDelaySeconds: 3
          periodSeconds: 10
        resources:
          requests:
            memory: "128Mi"
            cpu: "100m"
          limits:
            memory: "256Mi"
            cpu: "500m"
      volumes:
      - name: tls-certs
        secret:
          secretName: readwise-mcp-tls
---
apiVersion: v1
kind: Service
metadata:
  name: readwise-mcp
spec:
  type: LoadBalancer
  selector:
    app: readwise-mcp
  ports:
  - name: https
    port: 8443
    targetPort: https

自定义配置

# kustomization.yml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: mcp

resources:
- readwise-mcp.yml
- auth/

labels:
- includeSelectors: true
  pairs:
    app: readwise-mcp

images:
- name: readwise-mcp-server
  newName: docker.io/youruser/readwise-mcp-server
  newTag: latest

部署

kustomize build . | kubectl apply -f -

可选：垂直Pod自动缩放器

apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: readwise-mcp
spec:
  targetRef:
    apiVersion: apps/v1
    kind: StatefulSet
    name: readwise-mcp
  updatePolicy:
    updateMode: "Off"
  resourcePolicy:
    containerPolicies:
    - containerName: mcp
      controlledResources: ["cpu", "memory"]
      minAllowed:
        cpu: 50m
        memory: 64Mi
      maxAllowed:
        cpu: 1
        memory: 512Mi

发展

make build       # Build binary to build/readwise-mcp-server
make test        # Run tests with race detector
make lint        # Run go vet and golangci-lint
make container   # Build container image with Podman
make clean       # Remove build artifacts

许可证

麻省理工学院